Документация - один из самых ценных активов, который вы можете создать как инженер-программист, очевидно, самым ценным будет код, который вы создаете, и это прекрасно, однако во времена неверного понимания agile (не только agile) мы ( вся отрасль), как правило, попадают в ловушку, полагая, что документация - это какое-то «дополнительное» дополнение, которое можно пропустить и о котором можно позаботиться в неопределенном будущем. Проблема с этим мышлением в том, что в будущем - контекст исчезнет, ​​и без контекста вы не сможете создавать ценную документацию. Если эти слова вам не подходят - подумайте, как часто вы анализировали код, который написали сами через 6–9 месяцев, и буквально не могли понять его, просто взглянув на него. Чтобы создать хорошую документацию, вам нужно будет оценить текущую ситуацию в вашей компании и определить этап жизненного цикла продукта, над которым вы работаете. Эта оценка имеет решающее значение, потому что на основе результатов вы сможете предпринять правильные шаги и внести некоторую структуру и дисциплину в свой рабочий процесс.

Возможно ли, что мне не нужно создавать документацию?

Я могу представить только одну ситуацию, когда ответ на поставленный выше вопрос положительный - и это когда вы работаете над чем-то совершенно в одиночку, все вещи в вашей голове, и вам не нужно делиться контекстом с кем-либо, но даже тогда я был бы очень осторожен, решив не создавать никакой документации. Обычно, когда вы начинаете новый проект - вы пишете как минимум файл README, который является - может быть, это сюрприз - документацией. В сценарии, описанном выше, вы не должны добиваться своего будущего «я». Оставить некоторую документацию для «будущих» поколений - это всегда хорошая идея, и, честно говоря, никогда не знаешь, как будет развиваться проект и когда документация понадобится.

Необязательно быть чем-то огромным, но что-то, что позволит вам (или другим) намного быстрее перейти в контекст.

Структура

Самый важный и первый вопрос, который вам нужно задать себе: Кто будет в первую очередь полезен для документации? Другими словами - кто будет читать больше всего. Ответ на этот вопрос может отличаться в зависимости от потребностей вашей организации. Представьте, что у вас есть небольшая техническая группа из пяти человек, и есть решение, что ее нужно удвоить в течение следующих шести месяцев. В таком случае очевидный ответ заключается в том, что документация должна быть создана для технических специалистов, которые скоро присоединятся к вашей организации. Создавая такую ​​документацию, вы можете сэкономить себе и своей команде много времени, но, что также важно, ее можно использовать в будущем, когда технологическую команду нужно будет масштабировать еще раз.

По моему опыту - вы не можете обрабатывать документацию только с одной точки зрения, и я знаю, что мы, инженеры, склонны приближаться к потребностям других людей. Только по этой причине вам следует подумать о том, чтобы разделить вашу документацию на две части: техническую и бизнес-документацию. Структура начинает жить.

Структура деловой документации

Деловая документация сложна как внутренняя, так и внешняя. Что я имею в виду? Что ж, часть документации - это так называемое определение требований, которое вкратце можно описать как ожидания бизнеса в отношении программного обеспечения, которое мы производим. Эта часть документации внутренняя. Сторона вывода связана с конечным потребителем программного обеспечения - это ответ на вопрос: как использовать программное обеспечение? И я тоже верю и люблю хороший UX, но в сложных системах вы можете создать лучший UX в мире, и тем не менее вам понадобятся некоторые рекомендации - где найти переключатели и что произойдет, когда пользователь нажмет эту кнопку. Эта часть будет называться внешней.

Внутренняя документация компании

Как я уже упоминал - это часть документации, которая связана со всеми ожиданиями в отношении программной платформы. В идеальном мире у вас есть «деловые» люди, которые могут делать «открытия» и «эксперименты», а также на основе «данных» могут определять направление разработки программного обеспечения. В менее идеальном мире некоторые части процесса ушли, но результат тот же, нам, инженерам, нужно что-то создать. Мы находимся на этапе определения требований, которые при правильной реализации могут стать чрезвычайно ценным источником документации.

Кто отвечает за создание контента?

Владелец продукта, менеджер по продукту, основатели - как правило, это «бизнес» стороны организации, или, в более крупных, людей, занимающихся продуктом.

Кто отвечает за чтение содержания?

Вся организация, с упором на команду инженеров, как здесь инженеров, должна преобразовать бизнес-потребности в технологии.

Какие инструменты здесь могут работать, а какие нет?

Здесь - подумайте об участвующих группах, поскольку здесь мы говорим в основном о деловых людях - лучшие инструменты, которые можно использовать здесь, - это те, которые просты в использовании для нетехнических людей, и здесь я думаю, что это один из причины успеха слияния от Atlassian.

Инструменты здесь должны поддерживать следующие функции:

  • легкое сотрудничество между членами команды
  • простой интерфейс, которым могут пользоваться люди, не являющиеся техническими специалистами, то есть либо веб-интерфейс, либо простое в использовании настольное приложение
  • документы должны быть доступны только внутри организации
  • возможность экспортировать документы в такие форматы, как PDF, чтобы при необходимости поделиться с другими заинтересованными сторонами

Вот что я могу порекомендовать:

Какие здесь риски?

Самый большой риск здесь состоит в том, чтобы сместить «проблемное» пространство в «пространство решения». Что я имею в виду? Часто владелец продукта - бывший технический специалист, который склонен подробно описывать решения. Я считаю, что здесь нет места для этого, и эту работу нужно проделать позже. Также возможно, что описанные здесь проблемы не отражают потребности конечных пользователей, вот несколько хороших примеров: «Нам нужна интеграция с X?», Но невозможно найти ответ на то, зачем нам нужна интеграция с X и почему наша пользователям нужна эта интеграция.

Внешняя бизнес-документация

Это документация для клиентов, поэтому она должна быть красивой и полезной, так как внутренние пользователи многое вам простят, а внешние пользователи гораздо более требовательны, имейте это в виду.

Кто отвечает за создание контента?

Скорее всего, команда поддержки клиентов, и если у вас нет этой роли в вашей команде, кто-то, кто работает с клиентом, понимает его потребности, но также имеет глубокое понимание платформы.

Кто отвечает за чтение содержания?

Во-первых, клиенты, во-вторых, будут службой поддержки клиентов и любыми другими членами команды, которые хотели бы узнать, как все работает.

Какие инструменты здесь могут работать, а какие нет?

Он очень похож на предыдущий, но с некоторыми важными отличиями, о которых следует помнить. Поскольку это документация, предназначенная для клиентов, она должна быть безупречной, актуальной (чрезвычайно важно, нет ничего более разочаровывающего, чем устаревшая документация) и просто великолепно выглядеть. Он должен позволять искать темы / фразы в содержании и должен быть очень хорошо структурирован.

Что касается примеров - еще раз: Confluence, GitBook было бы хорошим выбором, но, кроме того, вы можете подумать о некоторых инструментах, которые будут генерировать документацию для вас, проблема здесь в том, что тогда вам, вероятно, понадобится кто-то из техническая поддержка для вас здесь (посмотрите, например, в справочном центре Slack) - но также здесь вы можете рассмотреть возможность использования некоторых SaaS, которые позволяют вам создать справочный центр для вашего продукта, их много, вы можете выбрать то, что лучше всего для ты.

Еще одна точка зрения, которую вы можете принять во внимание, заключается в том, что использование одного инструмента для всей бизнес-документации может быть выгодно для организации, вы можете легко перенаправить документы из одного источника в другой, все ваши пользователи должны поддерживать только одну службу, но я Могу поспорить, что это также зависит от размера вашей организации и стадии жизненного цикла.

Какие здесь риски?

Самый большой риск здесь заключается в том, что вы создадите справочный центр, который захочет использовать каждый ... Это может произойти по многим причинам, поэтому вам действительно следует проверять свои решения с вашими клиентами и командой. Поддержка справочного центра сама по себе является интересной темой, вы можете себе представить, что когда вы получаете слишком много запросов от пользователей по какой-либо теме, она либо отсутствует, либо ее трудно найти в документации, поэтому вам следует постоянно пересматривать и обновлять информацию. там.

Структура технической документации

Самый самый большой миф здесь заключается в том, что «вам вообще не нужна документация» или, другими словами: «Я пишу самодокументированный код ». Если вы все еще верите в это, вам обязательно стоит задуматься над этими мыслями еще раз. И не поймите меня неправильно, код может быть отличным источником документации, и обычно это так, но после некоторого порога сложности этого просто недостаточно.

Как мы можем структурировать техническую документацию?

В одном из недавних абзацев мы обсудили бизнес-требования, это входные данные для технической документации, вы просто берете ее и превращаете в набросок того, как определенные проблемы могут быть решены с использованием текущих технологий, которые у вас есть в организации, или идентифицировать места для совершенно новых решений, системных компонентов или технологий. Эта часть представляет собой чисто техническую документацию (но! На высоком уровне) и явно пересекается с деловой. Позже вы работаете над эскизами, пока они не будут готовы и не будут приняты вашей технологической командой. На этом этапе они готовы к реализации - единственное, чего не хватает, - это конвертировать результаты в тикеты, и да, тикеты также являются отличным источником документации.

Таким образом, мы смогли идентифицировать первую группу: Документация по технологиям для бизнеса. А как насчет других? Если у нас есть «бизнес-ориентированный», почти наверняка найдется тот, который не «бизнес-ориентированный» - и это правда, это будет второй сегмент, полностью понятный только технической команде.

Документация по технологиям для бизнеса

В этом пакете документации будет описано, как решать проблемы, которые выявляет бизнес. На этом уровне контент должен быть понятен даже нетехническим людям - например:

Чтобы решить эту проблему, нам нужно добавить новую модель базы данных, подключить ее к существующей пользовательской модели, написать API, спроектировать и реализовать представления в веб-приложениях и мобильных приложениях.

Очевидно, что это только первый набросок решения проблемы, поскольку, как видите, он требует гораздо большего количества итераций и «любви», но здесь стоит отметить, что на этом уровне вам не нужно точно указывать, как будет выглядеть новая модель. , какие поля у него будут и какие типы данных там используются, просто потому, что это слишком глубокий уровень детализации.

Кто отвечает за создание контента?

Техническая команда, обычно технический руководитель или старший специалист, способный определить и определить работу, которую необходимо выполнить для достижения данной функции или решения данной проблемы. Тем, кто хорошо разбирается в платформе, может потребоваться совместная работа между руководителями различных компонентов платформы.

Кто отвечает за чтение содержания?

Техническая группа, обычно это люди, которые будут предоставлять функцию или решать проблему, но также и деловые люди, которые заинтересованы и хотят больше узнать о предлагаемом решении - нет ничего необычного в том, что на этом уровне у вас будет возможность переключаться между разными организациями. единицы.

Какие инструменты здесь могут работать, а какие нет?

Как было сказано выше, на этом уровне это должен быть инструмент, обеспечивающий командную совместную работу и имеющий простой интерфейс - опять же, инструменты, подобные Confluence, GitBook, подходят. Здесь стоит отметить, что инструмент должен поддерживать циклы работы, редко бывает, чтобы такая документация составлялась за один присест, это итеративный процесс, поэтому такие вещи, как управление версиями, уведомления об изменениях, возможность упомянуть кого-то, кто может иметь решающее значение для определения области действия, все это должно быть возможно в этих инструментах.

Вдобавок к этому примечанию, что создаваемые вами тикеты также являются источником документации, поэтому соблюдайте дисциплину и делайте их чистыми и понятными. Здесь есть множество программ, которые помогают нам выполнять эту работу, поэтому я не буду рекомендовать ни одного, так как у каждого из нас есть любимое. Следует иметь в виду, что титульные билеты не подходят.

Какие здесь риски?

Главный риск здесь заключается в том, что инженеры подумают, что они владеют этой документацией, и сделают ее недоступной для других членов команды, что является большим грехом, и они сгниют в аду за это :) Независимо от того, нравится вам это или нет , у бизнеса есть свои собственные правила и приоритеты (и многие из этих правил определяются соотношением затрат и стоимости), и совместное использование контекста на этом уровне может помочь организации в принятии наилучших возможных решений.

Технологическая документация

И, наконец, мы находимся в ловушке того, что это ценно только для технологического подразделения, потому что уровень деталей здесь не может быть понят другим членам организации. Если задуматься, есть несколько источников такой документации:

  • код (очевидно)
  • вики-страницы (обычно доставляются VCS)
  • личные заметки
  • f2f разговоры с другими разработчиками
  • репозитории: структура, README
  • решения в виде инфраструктуры как кода

Код

Раньше я говорил: Code is the only source of truth. И все же мне ясно, что этот источник максимально приближен к истине. Это сама правда. Это очень связано с разделом «Дисциплина» ниже. В идеальном сценарии - вся информация, собранная вокруг кода, будет в том же состоянии, что и сам код, но по разным причинам - нехватка времени, как можно скорее режим, сосредоточиться на функциях, которые должны быть предоставлены, это не так. Вот почему важно найти баланс между хорошей и поддерживаемой документацией. Если вы тратите слишком много времени на документацию - делая ее превосходной, то, скорее всего, потребуется очень много времени, чтобы поддерживать ее в актуальном состоянии в будущем. С другой стороны, если вы создадите документацию, в которой практически не будет информации - в чем смысл?

Вы должны писать код, который легко понять, по моему опыту (не только моему), вы должны иметь в виду, что машина будет обрабатывать любой код, который вы напишете, но люди (программисты) не обязательно. Представьте, что вы старший и используете расширенные структуры кода, и ваша команда состоит в основном из юниоров, ваши младшие не смогут прочитать код или будут иметь реальные проблемы с его пониманием. Я бы действительно рекомендовал ставить перед вашими глазами «человеческую» природу кода каждый раз, когда вы что-то пишете.

В комментариях к коду это уже сказано, но будет сказано еще раз: «Самодокументированного кода не существует». Поместите туда комментарии, помня о нескольких вещах: поддерживайте их так же, как и код, убедитесь, что они обновляются, каждый раз, когда вы меняете соответствующий код, с другой стороны, не комментируйте очевидные вещи - это пустая трата времени. время, то я могу порекомендовать здесь писать вещи, которые объединяют технологические и бизнес-требования, поскольку эта часть часто отсутствует, когда мы переходим к другой функции.

Вики-страницы

Markdown, reStructuredText или другое? Это не имеет значения, в сети вы найдете множество статей, в которых у markdown нет стандарта, бла-бла. Это все правда, но с этой точки зрения гораздо важнее создаваемый вами контент, чем синтаксис, который вы используете для его создания. Даже с уценкой вы можете договориться с командой об одном стандарте и следовать правилам, мой опыт показывает, что уценка имеет более низкий входной барьер и поддерживается большим количеством инструментов. Например, часто бывает так, что вы можете создать документ с уценкой и добавить его с форматированием в такие инструменты, как Confluence, что нелегко с reStructuredText (насколько мне известно). С другой стороны, reStructuredText будет намного лучше для инструментов, создающих документацию, таких как sphinx для python или readthedocs. Здесь вам просто нужно договориться со своей командой и установить стандарт, которому вы все следуете. Вы также можете придерживаться необработанного формата вики, предоставляемого VCS, что тоже полезно, так как тогда вы можете просматривать документацию прямо из своей IDE.

Личные заметки

Эта часть забавная, я знаю много разработчиков, у которых есть секретный каталог в файловой системе с различными типами заметок: заметки с разъяснением бизнес-требований о встречах, почему они что-то делают, рабочий журнал и многое другое - вы называете это. Обычно это очень личное и должно оставаться таким, но здесь - я могу помочь вам управлять такими заметками. Раньше я использовал атом для подобных вещей, но атом почему-то не помогает мне организовать все записи, которые я делаю, поэтому недавно я переключился на обсидиан - он поддерживает уценку и позволяет строить графы зависимостей между разные заметки, если вы тоже делаете такие заметки, попробуйте.

f2f беседы и встречи

Не делай этого. Не волнуйтесь, просто шучу. Беседы являются ключевыми элементами нашей работы, поэтому вы должны вести их сколько угодно, но не более того. Ключевым моментом здесь является то, что вы должны задокументировать каждое решающее и важное решение, которое было принято во время бесед, особенно если это решение влияет на других членов команды, и они не присутствуют на собрании. В этом разделе мы также можем добавить все заметки, относящиеся к встречам команды, такие как ежедневные, ретроспективы и т. Д. Ключевой результат каждой встречи должен быть записан где-то в письменной форме - и причина этого проста - мы, люди, склонны забывать о вещах. . Также стоит отметить, что через некоторое время такая заметка может оказаться действительно полезной и объяснить вам, почему вы и ваша команда приняли некоторые решения и следуете определенным путям.

README

Хороший README - это искусство, и в Интернете есть много хороших статей на эту тему, например здесь.

Дисциплина

Документации без дисциплины не существует. Ведение документации может быть важной частью работы, и я думаю, что это основная причина, по которой люди этого не делают. В отрасли существует такое предубеждение, что инженеры не создают документацию, но я думаю, что это только одна сторона истины, и здесь роли продукта испытывают трудности.

Забавно и страшно в документации то, что она не приносит непосредственной пользы конечному потребителю (кроме, разумеется, справочного центра), поэтому вложения в эту область склонны к «лучшим временам». Проблема с этим подходом заключается в том, что маловероятно, что вы сможете создать качественную документацию по прошествии значительного количества времени. На мой взгляд, вам следует как можно быстрее внедрить процессы, связанные с документацией.

Конечно, возникает вопрос, насколько «глубоко» вы должны пойти - и здесь, вероятно, я не могу вам помочь, так как вам нужно самостоятельно оценить ситуацию, но вы должны быть в состоянии определить «количество» документации, необходимой на разных этапах жизни вашего ребенка. организация. Как упоминалось выше, когда ожидается рост вашей технологической команды, хорошая документация может стать ключевым фактором удовлетворения при приеме на работу новых сотрудников и в то же время ключевым фактором неудовлетворенности, когда это просто плохо.

Чтобы документация работала в вашей организации, вам нужны процесс и дисциплина, и все члены команды должны знать, чего ожидать от создания контента.

Последние мысли

Я планировал написать несколько слов о документации в организации, но на самом деле закончил касанием областей управления Базой знаний, собранные здесь наблюдения основаны в основном на моем опыте, я читал несколько статей об этом за свою жизнь, но я Я не считаю себя здесь экспертом, однако я знаю, что контекст и знания чрезвычайно важны, и их просто нельзя игнорировать, потому что при игнорировании они взорвутся в будущем, нанеся ущерб, который трудно оценить . Основные области, обсуждаемые в этой статье, представлены на графике ниже:

Начиная с этого момента, вы можете выбрать области, которые вас особенно интересуют, не беритесь за все сразу, так как это будет слишком много, но отразите то, что нужно в данный момент, и начните работать над новой идеальной документацией.

Спасибо за чтение.