Для меня написание документации — это почти как возвращение к истокам. Если вы играли в некоторые видеоигры, вам может быть знакома концепция, когда продвинутый игрок попадает в новую среду, где ему приходится начинать с самого начала (постоянно или временно). В Assassins Creed Valhalla, например, после примерно 50 часов игры я попал в другую локацию, которая практически сбрасывает ваше снаряжение до базового (что было интересным испытанием после сбора лучших доспехов в игре), так что вам пришлось еще больше использовать свои навыки и начинать собирать снаряжение заново. Это действительно освежает. И для меня это то же самое, что и написание документации.
Документация для разработчиков
Вы глубоко погружаетесь в разработку своего продукта или проекта, поэтому вы уже очень хорошо его знаете. Сделав шаг назад и позиционируя себя как обычного пользователя вашего продукта, вы сможете улучшить юзабилити, опыт разработчиков и пользователей, а также общие отношения с разработчиками. Имейте в виду, что я не пытаюсь убедить вас стать автором документации на полный рабочий день. Я считаю, что если вы будете посвящать часть своего времени написанию документации, то в долгосрочной перспективе станете лучшим разработчиком.
Точное знание того, какую проблему вы пытаетесь решить, как пользователи используют продукт, где они терпят неудачу и т.д., позволит вам лучше решать проблемы. А это то, что лучше всего получается у разработчиков — решать проблемы.
Документация для разработчиков
Это перспектива разработчиков, пишущих документацию, но как насчет другой части, а именно разработчиков, которые используют документацию? Это еще более важно! Просвещение пользователей о ваших продуктах особенно важно, если вы хотите иметь сообщество или клиентов.
Помню, в 2017 году я начал изучать Vue.js, и официальная документация по Vue была просто великолепна для этого.
Год спустя я попробовал Nuxt.js и был действительно поражен примерами кода, которые решали большинство моих проблем.
Наконец, в 2019 году я начал изучать Nest.js, и эта документация была и остается лучшей, на мой взгляд.
Документация рассказывает о том, как легко создавать как простые, так и продвинутые приложения. Помимо письменной документации, в репозитории GitHub есть несколько примеров приложений, которые вы можете посмотреть, если у вас возникают трудности с некоторыми темами.
Мой опыт работы с документацией
За свою карьеру я написал несколько страниц документации для больших и малых проектов. Это, конечно, не работа на полный рабочий день, но потратить несколько часов в неделю на написание учебников и объяснение основных тем — отличный способ лучше понять потребности пользователей.
Я начал с переписывания документации по Storefront UI — библиотеке пользовательского интерфейса на базе Vue.js специально для электронной коммерции -> https://docs.storefrontui.io. Она была создана с использованием Storybook, поэтому больше похожа на документацию по игровой площадке, но она хорошо справляется со своей задачей. Мне понравилось объяснять, как работает каждый компонент, как интегрировать SFUI с Tailwind, Cloudinary и т.д. Кроме того, я подумал о реструктуризации документации таким образом, чтобы она в первую очередь решала проблемы текущих пользователей. Это был отличный ход, который помог разработчикам узнать, как правильно использовать Storefront UI.
После этого я написал несколько документаций для продуктов Vue Storefront и внутренних проектов и нашел это особенно интересным, поскольку мне пришлось поставить себя на место обычных пользователей.
Наконец, я написал несколько сайтов документации, связанных с Nuxt.js, например https://algolia.nuxtjs.org/. Там я очень много внимания уделил написанию руководства шаг за шагом, чтобы пользователи могли легко начать его использовать.
Резюме
Писать документацию — это здорово, и вам обязательно стоит попробовать. Это позволит вам лучше понять своих пользователей. Более того, это поможет вам решить проблемы ваших пользователей до того, как они с ними столкнутся.