Если вы заинтересованы в создании документа о дизайне программного обеспечения, важно знать, какие шаги необходимо предпринять для его написания и какую информацию в него включить. В этой статье мы обсудим определение документа по проектированию программного обеспечения, как его написать и какие элементы необходимо включить.
Что такое проектный документ?
Документ по разработке программного обеспечения — это набор материалов, описывающих дизайн продукта. Разработчики программного обеспечения пишут эти документы, чтобы описать продукт и то, для чего он предназначен.
Почему важен проектный документ?
Документ о дизайне программного обеспечения создается до завершения разработки продукта для подтверждения ожиданий заинтересованных сторон. Документ о дизайне программного обеспечения также может помочь вам устранить проблемы до написания кода и позволяет создать эффективный рабочий процесс для завершения проекта.
Как написать проектный документ
При написании документа по разработке программного обеспечения необходимо включить определенные элементы. Ниже перечислены общие моменты, которые необходимо включить в документ о разработке программного обеспечения:
Читай документацию! | Вы сломали программирование
Описание проекта
Этот раздел будет содержать подробное описание предполагаемой функции программного обеспечения, включая то, как предполагается использовать программное обеспечение, как будут устраняться ошибки пользователя и какие решения ваш проект решает для пользователя.
Пользовательский интерфейс
Если ваш проект — это приложение, то вы захотите упомянуть все компоненты пользовательского интерфейса. Вы должны убедиться, что все заинтересованные стороны понимают, что должно быть включено в документ, чтобы не возникло недопонимания относительно компонентов пользовательского интерфейса.
Пользователи
В документ по разработке программного проекта следует включить информацию о предполагаемых пользователях вашего продукта или приложения. Это поможет объяснить, какие функции ожидает и требует ваш предполагаемый пользователь.
Характеристики и цели проекта
Важно, чтобы в документе по разработке программного обеспечения содержалось описание каждой из функций вашего проекта в порядке их важности. Неплохо также включить все цели вашего проекта.
Предполагаемые сроки реализации проекта
Обязательно включите в резюме рабочий процесс с указанием всех ожидаемых результатов и сроков их выполнения, а также сроков, когда вы ожидаете завершить каждый из них.
Пути пользователя
В этом разделе описывается, часто как визуально, так и словами, путь, который проходит потребитель при использовании продукта. Если продукт решает конкретную проблему, в этом разделе можно описать, как потребитель решает эту проблему с помощью продукта. Этот раздел может включать визуальную временную шкалу пути пользователя или другие хронологические шаги, связанные с достижением целей потребителя.
Руководства по стилю
Внешний вид и другие стилистические элементы продукта важны как для потребителей, так и для инвесторов, поскольку они во многом определяют покупательские привычки потребителей. В этом разделе подробно описываются все цвета, формы, шрифты, материалы и эстетика, которые вы используете в дизайне продукта. Наглядные пособия также могут помочь проиллюстрировать выбор стиля в этом разделе.
Как оформить реферат по ГОСТУ 2020 года за 5 минут (Пример правильного оформления)
План реализации
Этот план включает в себя всю информацию о реализации выбора дизайна продукта. Элементы дизайна продукта могут быть простыми в реализации или более сложными, поэтому важно объяснить, как вы планируете производить продукты, которые разрабатываете.
Тестирование пользователей
В этом разделе опишите, как вы планируете проверять качество продукта, чтобы определить, соответствует ли он желаниям потребителей. Этот раздел особенно полезен, если вашей целевой аудиторией являются инвесторы, поскольку он может помочь доказать, что для вашего продукта в его нынешнем состоянии существует рынок. Пользователи также могут предоставить ценную обратную связь для внесения будущих изменений в дизайн продукта.
Оперативные инструкции
Эта документация включает информацию, относящуюся к работе предприятия во время реализации дизайна продукта. Например, если выходит новая версия продукта, в этом разделе можно подробно описать, как вы планируете доставить новый продукт потребителям, или объяснить, как производить новый продукт. Инвесторы могут быть заинтересованы в этой информации, чтобы определить затраты и персонал, связанные с реализацией дизайна продукта.
Советы по правильному документированию дизайна
Ключевые слова:
Источник: hr-portal.ru
Как написать документацию для вашего следующего проекта
Перевод статьи «How to Write Documentation For Your Next Software Development Project».
У вас на горизонте замаячил новый проект? Наличие правильно составленной документации — важный аспект в деле обеспечения бесперебойной работы над ним.
Прежде чем приступить к проектированию, написанию кода, сборке и тестированию, уделите время подготовке всей необходимой вам документации. Это не самая захватывающая часть проекта, но она имеет большое значение.
В чем важность документации?
Сфера разработки ПО — одна из тех, которые развиваются особенно быстро. Пытаясь выдерживать темп, вы можете решить, что как только в голову пришла хорошая идея, нужно сразу браться за написание кода. Но попридержите лошадей. Попытка срезать угол на самом деле ничего вам не даст.
Работая над документацией, вы не теряете время. Напротив, вы даже сможете его сэкономить (если подойдете к делу с умом), да еще и улучшить свой продукт. По мере роста проекта документация станет руководством, позволяющим делать все правильно с первой попытки. Никаких догадок, никакой самодеятельности — сплошной профессионализм.
Если у менеджера проекта есть прекрасное понимание этого проекта и видение того, каким должен быть продукт, — это прекрасно. Беда в том, что если все это у менеджера только в голове, разработчики или новые члены команды не смогут получить доступ к этому видению и пониманию. А в процессе коммуникации некоторые детали могут потеряться.
Состояние технической документации может послужить как залогом успеха проекта, так и одной из причин его провала. Если каждый этап проекта хорошо задокументирован, работа будет продвигаться плавно и в итоге вы сэкономите время. Чтобы донести до занятых в проекте людей важную информацию, вам не придется общаться с каждым из них лично. При этом также снизится возможность недопониманий.
Зачем писать проектную документацию?
Ваш проект будет меньше зависеть от отдельных людей
Благодаря подробной документации значительно упрощается подключение к работе новых членов команды. По мере роста, изменения и масштабирования продукта вы сможете направлять новых сотрудников к необходимой документации и таким образом быстро вводить их в курс дела.
Это работает и в обратную сторону: если член команды уйдет, он не заберет с собой все свои знания о проекте. Все они останутся в документации.
Упрощается коммуникация со стейкхолдерами и клиентами
Преимущества хорошо задокументированного проекта ПО выходят за рамки внутренних процессов.
С правильной документацией также становится легче представить свой продукт заинтересованным сторонам. Все, что написано на бумаге, легче рассмотреть и понять, чем идеи в чьей-то голове.
В общем, документация продукта помогает в процессе питчинга. Но этим дело не ограничивается! Если клиент одобрил представленные вами документы, вам будет легко прибегнуть к ним при возникновении проблем. Никаких «а вот он сказал, а она сказала»: вся информация сохранена в одном месте и на нее можно ссылаться.
Наконец, успешный проект — это не только продукт, который вы создаете, но и отношения, которые вы строите. Предупреждая как можно большее число проблем, вы обеспечите команде приятную совместную работу.
Как написать хорошую документацию
Хотим отметить, что для всего вышеперечисленного вовсе не нужна документация объемом с Большую советскую энциклопедию. Вам нужно лишь проследить за тем, чтобы в ней были охвачены самые главные части и особенности вашего проекта. В этой статье мы дадим вам несколько советов, как это сделать.
Составьте перечень необходимых документов
У вас в голове уже спланирован весь проект? Это отличное начало, но лучше все же задокументируйте свой план. Если вы не видите смысла создавать какую-либо документацию для себя, помните, что вы делаете это в основном для пользователей вашего конечного продукта.
Люди заметят не только то, насколько хорошо работает ваша программа, но и то, насколько быстро она была создана, а также то, что вам не пришлось вносить кучу правок после запуска.
Какие документы вам понадобятся для этого? Это во многом определяется размерами проекта. Возможно, вам потребуется документация, которая будет служить справочником для повседневных процессов. А может, вам нужна скорее схема крупного плана картины.
Давайте разделим документацию ПО на две категории: документацию процесса и документацию продукта.
Что такое документация продукта?
Документация продукта описывает конечную цель: собственно продукт, который вы создаете. Как он работает, как с ним работать, технологические спецификации, руководства пользователя — все то, что может понадобиться, когда продукт уже будет реализован.
Для ваших разработчиков самая важная документация продукта — это системная документация. В ней объясняется, как работает программа, почему она работает определенным образом и как с ней работать.
Для пользователей вашей программы крайне важна пользовательская документация. Это учебные пособия, FAQ по устранению неполадок и, конечно, руководство пользователя, которое поможет людям использовать ваш продукт так, как вы планировали.
Что такое документация процесса?
Считайте ее дорожной картой, которая проведет ваш проект от идеи к реализации. Эта документация может включать:
- Стандарты и графики тестирования. Они помогут обеспечить единообразие в тестировании, благодаря чему результаты будут релевантными.
- Заметки с совещаний: сохраните их, чтобы иметь доказательства при спорах с клиентами.
- Планы проекта. Как вы будете строить свой продукт? На какие этапы будет разделен процесс разработки, когда вы планируете завершить работу над каждым из этапов?
Определите критически важную информацию
Что касается документации процесса, только вам решать, насколько подробно вы будете ее расписывать. Если вы опытный разработчик или руководитель проекта, вы можете предположить, какие вопросы и дискуссии могут возникнуть в дальнейшем.
Если вы новичок в этом деле, вероятно, вы и понятия не имеете, что нужно включить в документацию. Вот несколько вещей, которые вы могли упустить из виду, но которые могут ускорить разработку вашего проекта:
Соблюдение конфиденциальности
Если это релевантно для вашего продукта, создайте руководство, которое поможет вашей команде не выйти за рамки дозволенного в отношении сбора и обработки личных данных. Прежде всего, опишите требования законодательства. Распишите процедуру, следуя которой сотрудники смогут быть уверенными в своих действиях.
Планы действий в чрезвычайных ситуациях
Что делать, если упал сервер? Каковы должны быть первые шаги при обнаружении взлома системы безопасности? Что делать, если оборудование внезапно решит объявить забастовку? Если у вас будут четко прописанные ответы на подобные вопросы, это сэкономит вам много времени и денег.
Визуализация
Техническая документация — это не только слова. Люди по-прежнему лучше всего воспринимают информацию визуально. Поэтому диаграммы могут помочь вам сделать рабочие процессы более понятными.
Но визуализация того, как продукт должен работать в итоге, тоже способствует более рациональному подходу к работе. Особенно это касается сложных проектов.
Все еще не знаете, что включить в документацию? Спросите мнение заинтересованных людей. Сядьте с командой за стол и вместе решите, что они хотят видеть на бумаге. Это поможет избежать многих проблем.
Пишите технические документы эффективно
Не волнуйтесь, сейчас разберем как это сделать. Не все одарены писательским талантом и уж точно не все мы являемся прирожденными техническими писателями. Создание технических документов может показаться скучной и в то же время сложной задачей. Сложность в том, что ошибка в техническом документе может иметь очень серьезные последствия для продукта или процесса. Ошибки в руководстве пользователя тоже опасны.
Следите за языком
Не нужно стараться произвести впечатление на читателя. Члены вашей команды и так знают, что вы умный; не надо в качестве доказательства щеголять техническим жаргоном там, где это просто не нужно.
Когда речь идет о деловых документах, многих людей просто тянет использовать более сложный язык. Но при написании документации вы обращаетесь к живым людям. И у вас уже сложился какой-то стиль общения с ними, какой-то общий язык. Постарайтесь сохранить все это (стиль и язык) в письменной речи. Так ваши документы станут более понятными.
Предложения должны быть короткими. Используйте слова попроще. Старайтесь не допустить недопонимания.
Цель технической документации — объяснять непонятное и таким образом ускорять процессы. Документация не должна порождать еще больше вопросов. Особенно это касается документации, предназначенной для конечного пользователя.
Если хотите получить бонусные очки, попробуйте написать разную документацию для разных пользователей. Возьмем к примеру Python. По этому языку есть отличная документация для самых разных пользователей, от новичков до опытных профессионалов.
Организуйте свои мысли
Да, если вы планируете написать план, вам нужно спланировать его написание. Четкая структура технической документации экономит время читателей. Используйте заголовки. Упорядочивайте вещи хронологически.
Если это ваше первое родео, начните с использования готового шаблона для технического документа. Не нужно заново изобретать велосипед.
Проверьте написанное
Дайте кому-нибудь другому почитать вашу техническую документацию, чтобы убедиться, что она проста для понимания и охватывает все важные аспекты.
Слишком часто руководства пользователя рассматриваются как побочный продукт и не включаются в тестирование. И совершенно напрасно.
Облегчите себе работу над будущими проектами
Создание технической документации приносит пользу не только проекту, над которым вы сейчас работаете. Поскольку у вас уже будет наработанная схема, вам будет проще составлять документацию для всех будущих проектов. Вам нужно будет лишь внести необходимые изменения, касающиеся вашего продукта, учесть прошлый опыт и — вуаля! — вы готовы приступить к разработке.
Источник: techrocks.ru
Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому
Больше пяти лет я занимаюсь бизнес-процессами. В особенности процессами технической поддержки, которую мы оказываем коммерческим и государственным компаниям. Например, я слежу, чтобы уровень качества IT-обслуживания соответствовал международным стандартам. Я программирую и работаю с документацией — пишу регламенты и процедуры, описываю процессы, выпускаю инструкции.
Всё это время я неосознанно «перетаскиваю» общие принципы программирования в работу с документами. Это помогает мне не делать бесполезные «спагетти-простыни» и писать внятные рабочие документы с ясной структурой, даже если документация очень объёмная и должна часто меняться в соответствии с изменениями в компании и все её части должны быть связаны воедино, чётко объяснять, как что-то работает. Возможно, мои приёмы помогут и вам.
Принципы работы с текстом
DRY — Don’t repeat yourself. Не повторяйся
Если вы вставили один и тот же блок в 10 разных регламентов и что-то меняете в нём, то у вас образуется 10 одинаковых мест, куда нужно внести одинаковые изменения. Вероятность забыть об этом тоже растёт, даже если вы пользуетесь бессмертным «Ctrl+C» — «Ctrl+V». Особенно в последней паре документов.
В программировании такие блоки выделяют в отдельные функции, классы, а в работе с документами повторяющиеся элементы нужно выносить в отдельные разделы или документы и давать ссылки на них.
KISS — Keep it simple, stupid. Не усложняй
Посмотрите вокруг: люди привыкли к простоте. Интуитивно понятные интерфейсы и всплывающие подсказки в приложениях. Принцип одного окна в IT-обслуживании. Засилье коротких статей и обучающих видео в Интернете. Той же простоты они ждут и от рабочих документов.
Этот принцип я обычно использую как маркер. Если описание процесса слишком сложное — нужно упростить процесс. Если инструкция к приложению слишком замысловатая — надо доработать приложение.
Обычно это проще и дешевле, чем писать сложную документацию, заставлять каждого нового сотрудника её читать, понимать и учиться действовать по ней. А ведь потом ещё нужно будет вносить изменения в документацию.
YAGNI — You ain’t gonna need it. Тебе это не понадобится
Это продолжение принципа KISS. Обычно я применяю его, когда собираюсь создать универсальное решение с заделом на будущее. Проблема в том, что такое решение — само по себе усложнение. Не факт, что в будущем оно понадобится. Обычно нет смысла создавать всеобъемлющее описание бизнес-процессов направления, которое только сформировалось и активно развивается.
Практика показывает, что будущее внесёт серьёзные коррективы.
Но здесь важно разумно подходить к вопросу. Есть вещи, изменение которых дорого обходится. Их как раз нужно готовить с заделом на будущее. В программировании эту работу относят к архитектуре приложения, а в документации просто сразу говорят: «Это нам не понадобится». И в будущем с трудом навёрстывают упущенное.
Принципы работы со структурой
Чем объёмнее становится документация, тем сложнее поддерживать её актуальность. Изменение одного документа влечёт за собой каскадное изменение остальных, логическая целостность ломается, структура требует очередной переработки. К счастью, для программирования это стандартная проблема, и за прошедшие десятилетия выработались общие принципы написания легко поддерживаемого кода. Часть из них можно применять и к документам.
SRP — Single Responsibility Principle. Принцип единственной ответственности
Яркий маркер нарушения принципа — наличие побочных действий. Например, метод класса отвечает за отправку клиенту уведомления о новом заказе в интернет-магазине, но при этом ещё и обновляет текущий баланс клиента.
То же самое справедливо и для документации. Например, в регламент регистрации обращения клиента не нужно впихивать что-то «заодно»: принципы вежливого общения с клиентами, краткое описание self-service портала и т. д.
Нельзя рассчитывать, что такая информация будет усвоена или сотрудники запомнят, к какому документу нужно обращаться, чтобы её получить. Зато это запутывает документ, лишает структуру чёткости и требует дополнительного времени для актуализации. Если вы действительно хотите напомнить о вежливости при общении с клиентом, вставьте в регламент ссылку на соответствующий документ (вспомните о DRY).
Соблюдение принципа позволяет делать документы короче. Их название соответствует назначению, а чтение не вызывает неприятных сюрпризов. Их проще прочитать за раз. И не забыть, с чего документ начинался.
SLAP — Single Level of Abstraction Principle. Принцип единого уровня абстракции
Является логичным продолжением принципа единственной ответственности (SRP).
Применение принципов KISS и SRP побуждает писать небольшие, простые и понятные документы. Но эти документы нужно собрать в такую же простую и понятную структуру. Здесь помогает выделение и соблюдение уровней абстракций.
Например, очевидно, что нет смысла пытаться поместить в один огромный документ объёмную документацию вроде описания системы менеджмента качества. Намного логичнее разбить его на уровни абстракций и сделать для каждого уровня разные документы — верхнеуровневое описание системы, описание каждого процесса и т. д.
При этом важно соблюдать принцип единого уровня абстракций и относить информацию только к нужному уровню. Если вы пишете верхнеуровневое описание, не надо вдаваться в детали работы конкретного процесса. Не тот уровень абстракции! Оставьте эту информацию для описания процесса. Этот принцип дополняет SRP, заставляя автора контролировать не только то, за что отвечает документ, но и на каком уровне в иерархии он находится.
LoD — Law of Demeter (Don’t talk to strangers). Закон Деметры (Не разговаривай с незнакомцами)
Если применить закон к документации, то каждый документ:
- Должен обладать ограниченным знанием о других документах, т. е. «знать» только тех, которые имеют к нему непосредственное отношение.
- Должен взаимодействовать только с известными ему документами-«друзьями» и не «разговаривать» с незнакомцами.
- Обращаться только к «друзьям».
Например, процесс управления IT-инцидентами взаимодействует с процессом управления проблемами напрямую, а с процессом управления изменениями — только через управление проблемами. Тогда в описании управления инцидентами можно ссылаться на описание управления проблемами. А вот ссылаться на описание управления изменениями не надо.
Итого
Указанные выше принципы сильно помогают мне при написании документации по процессам, в создании регламентов, процедур и инструкций. К сожалению, это лишь небольшая часть рекомендаций по управлению качеством кода, поэтому заинтересовавшимся рекомендую самостоятельно углубиться в тему. Из неё можно извлечь много полезного.
При этом важно помнить, что эти принципы не являются законами. В Интернете много спорят об их правильном использовании и часто злоупотребляют ими. Поэтому, пожалуйста, не впадайте в крайности. И не забывайте о здравом смысле.
Источник: tproger.ru