Перевод статьи «How to Write Documentation For Your Next Software Development Project».
У вас на горизонте замаячил новый проект? Наличие правильно составленной документации — важный аспект в деле обеспечения бесперебойной работы над ним.
Прежде чем приступить к проектированию, написанию кода, сборке и тестированию, уделите время подготовке всей необходимой вам документации. Это не самая захватывающая часть проекта, но она имеет большое значение.
В чем важность документации?
Сфера разработки ПО — одна из тех, которые развиваются особенно быстро. Пытаясь выдерживать темп, вы можете решить, что как только в голову пришла хорошая идея, нужно сразу браться за написание кода. Но попридержите лошадей. Попытка срезать угол на самом деле ничего вам не даст.
Работая над документацией, вы не теряете время. Напротив, вы даже сможете его сэкономить (если подойдете к делу с умом), да еще и улучшить свой продукт. По мере роста проекта документация станет руководством, позволяющим делать все правильно с первой попытки. Никаких догадок, никакой самодеятельности — сплошной профессионализм.
Если у менеджера проекта есть прекрасное понимание этого проекта и видение того, каким должен быть продукт, — это прекрасно. Беда в том, что если все это у менеджера только в голове, разработчики или новые члены команды не смогут получить доступ к этому видению и пониманию. А в процессе коммуникации некоторые детали могут потеряться.
Состояние технической документации может послужить как залогом успеха проекта, так и одной из причин его провала. Если каждый этап проекта хорошо задокументирован, работа будет продвигаться плавно и в итоге вы сэкономите время. Чтобы донести до занятых в проекте людей важную информацию, вам не придется общаться с каждым из них лично. При этом также снизится возможность недопониманий.
Зачем писать проектную документацию?
Ваш проект будет меньше зависеть от отдельных людей
Благодаря подробной документации значительно упрощается подключение к работе новых членов команды. По мере роста, изменения и масштабирования продукта вы сможете направлять новых сотрудников к необходимой документации и таким образом быстро вводить их в курс дела.
Это работает и в обратную сторону: если член команды уйдет, он не заберет с собой все свои знания о проекте. Все они останутся в документации.
Упрощается коммуникация со стейкхолдерами и клиентами
Преимущества хорошо задокументированного проекта ПО выходят за рамки внутренних процессов.
С правильной документацией также становится легче представить свой продукт заинтересованным сторонам. Все, что написано на бумаге, легче рассмотреть и понять, чем идеи в чьей-то голове.
В общем, документация продукта помогает в процессе питчинга. Но этим дело не ограничивается! Если клиент одобрил представленные вами документы, вам будет легко прибегнуть к ним при возникновении проблем. Никаких «а вот он сказал, а она сказала»: вся информация сохранена в одном месте и на нее можно ссылаться.
Наконец, успешный проект — это не только продукт, который вы создаете, но и отношения, которые вы строите. Предупреждая как можно большее число проблем, вы обеспечите команде приятную совместную работу.
Как написать хорошую документацию
Хотим отметить, что для всего вышеперечисленного вовсе не нужна документация объемом с Большую советскую энциклопедию. Вам нужно лишь проследить за тем, чтобы в ней были охвачены самые главные части и особенности вашего проекта. В этой статье мы дадим вам несколько советов, как это сделать.
Составьте перечень необходимых документов
У вас в голове уже спланирован весь проект? Это отличное начало, но лучше все же задокументируйте свой план. Если вы не видите смысла создавать какую-либо документацию для себя, помните, что вы делаете это в основном для пользователей вашего конечного продукта.
Люди заметят не только то, насколько хорошо работает ваша программа, но и то, насколько быстро она была создана, а также то, что вам не пришлось вносить кучу правок после запуска.
Какие документы вам понадобятся для этого? Это во многом определяется размерами проекта. Возможно, вам потребуется документация, которая будет служить справочником для повседневных процессов. А может, вам нужна скорее схема крупного плана картины.
Давайте разделим документацию ПО на две категории: документацию процесса и документацию продукта.
Что такое документация продукта?
Документация продукта описывает конечную цель: собственно продукт, который вы создаете. Как он работает, как с ним работать, технологические спецификации, руководства пользователя — все то, что может понадобиться, когда продукт уже будет реализован.
Для ваших разработчиков самая важная документация продукта — это системная документация. В ней объясняется, как работает программа, почему она работает определенным образом и как с ней работать.
Для пользователей вашей программы крайне важна пользовательская документация. Это учебные пособия, FAQ по устранению неполадок и, конечно, руководство пользователя, которое поможет людям использовать ваш продукт так, как вы планировали.
Что такое документация процесса?
Считайте ее дорожной картой, которая проведет ваш проект от идеи к реализации. Эта документация может включать:
- Стандарты и графики тестирования. Они помогут обеспечить единообразие в тестировании, благодаря чему результаты будут релевантными.
- Заметки с совещаний: сохраните их, чтобы иметь доказательства при спорах с клиентами.
- Планы проекта. Как вы будете строить свой продукт? На какие этапы будет разделен процесс разработки, когда вы планируете завершить работу над каждым из этапов?
Определите критически важную информацию
Что касается документации процесса, только вам решать, насколько подробно вы будете ее расписывать. Если вы опытный разработчик или руководитель проекта, вы можете предположить, какие вопросы и дискуссии могут возникнуть в дальнейшем.
Если вы новичок в этом деле, вероятно, вы и понятия не имеете, что нужно включить в документацию. Вот несколько вещей, которые вы могли упустить из виду, но которые могут ускорить разработку вашего проекта:
Соблюдение конфиденциальности
Если это релевантно для вашего продукта, создайте руководство, которое поможет вашей команде не выйти за рамки дозволенного в отношении сбора и обработки личных данных. Прежде всего, опишите требования законодательства. Распишите процедуру, следуя которой сотрудники смогут быть уверенными в своих действиях.
Планы действий в чрезвычайных ситуациях
Что делать, если упал сервер? Каковы должны быть первые шаги при обнаружении взлома системы безопасности? Что делать, если оборудование внезапно решит объявить забастовку? Если у вас будут четко прописанные ответы на подобные вопросы, это сэкономит вам много времени и денег.
Визуализация
Техническая документация — это не только слова. Люди по-прежнему лучше всего воспринимают информацию визуально. Поэтому диаграммы могут помочь вам сделать рабочие процессы более понятными.
Но визуализация того, как продукт должен работать в итоге, тоже способствует более рациональному подходу к работе. Особенно это касается сложных проектов.
Все еще не знаете, что включить в документацию? Спросите мнение заинтересованных людей. Сядьте с командой за стол и вместе решите, что они хотят видеть на бумаге. Это поможет избежать многих проблем.
Пишите технические документы эффективно
Не волнуйтесь, сейчас разберем как это сделать. Не все одарены писательским талантом и уж точно не все мы являемся прирожденными техническими писателями. Создание технических документов может показаться скучной и в то же время сложной задачей. Сложность в том, что ошибка в техническом документе может иметь очень серьезные последствия для продукта или процесса. Ошибки в руководстве пользователя тоже опасны.
Следите за языком
Не нужно стараться произвести впечатление на читателя. Члены вашей команды и так знают, что вы умный; не надо в качестве доказательства щеголять техническим жаргоном там, где это просто не нужно.
Когда речь идет о деловых документах, многих людей просто тянет использовать более сложный язык. Но при написании документации вы обращаетесь к живым людям. И у вас уже сложился какой-то стиль общения с ними, какой-то общий язык. Постарайтесь сохранить все это (стиль и язык) в письменной речи. Так ваши документы станут более понятными.
Предложения должны быть короткими. Используйте слова попроще. Старайтесь не допустить недопонимания.
Цель технической документации — объяснять непонятное и таким образом ускорять процессы. Документация не должна порождать еще больше вопросов. Особенно это касается документации, предназначенной для конечного пользователя.
Если хотите получить бонусные очки, попробуйте написать разную документацию для разных пользователей. Возьмем к примеру Python. По этому языку есть отличная документация для самых разных пользователей, от новичков до опытных профессионалов.
Организуйте свои мысли
Да, если вы планируете написать план, вам нужно спланировать его написание. Четкая структура технической документации экономит время читателей. Используйте заголовки. Упорядочивайте вещи хронологически.
Если это ваше первое родео, начните с использования готового шаблона для технического документа. Не нужно заново изобретать велосипед.
Проверьте написанное
Дайте кому-нибудь другому почитать вашу техническую документацию, чтобы убедиться, что она проста для понимания и охватывает все важные аспекты.
Слишком часто руководства пользователя рассматриваются как побочный продукт и не включаются в тестирование. И совершенно напрасно.
Облегчите себе работу над будущими проектами
Создание технической документации приносит пользу не только проекту, над которым вы сейчас работаете. Поскольку у вас уже будет наработанная схема, вам будет проще составлять документацию для всех будущих проектов. Вам нужно будет лишь внести необходимые изменения, касающиеся вашего продукта, учесть прошлый опыт и — вуаля! — вы готовы приступить к разработке.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
