Автор оригинала: Vyacheslav.
Почему документация не может быть проектом?
Вступление
Эта статья, основанная на моем опыте, демонстрирует подход организации документации в вашем проекте, направленном на следующую:
- Сделайте более простым переходом проекта S/W для поддержки
- Получить единственную точку входа для обновлений и информации
- Получить проект документирован из нескольких углов
- Заставить своих заинтересованных сторон вовлечены
- Заставить своих разработчиков вовлечены
- Получить свои операции
- Получите вовлеченные ваши тестеры
Фон
Теперь я в разработке программного обеспечения более десяти лет. Раньше я работал в разных командах и на разных проектах, включая тот, который был передан на поддержку других команд и даже компаний.
На самых больших и наиболее обычных проблемах столкнулись, отсутствовали проектной документации. В количестве ситуаций было причиной более длительного времени, необходимого для владения проектом. Это не обычно неудача команды, иногда документация просто не включена в бюджет.
Вот почему я всегда пытался включить части знаний для будущей поддержки (даже для себя за несколько месяцев или лет)
Чаще всего мы работаем с подмножеством диаграмм, которые называются неофициально 4 + 1 архитектурный набор, я
Развитие Вид : Компонент, пакет Логический взгляд : Деятельность, государство, Класс Физический вид : развертывание Процесс : Деятельность, BPMN Сценарии : Используйте корпус
В более крупных проектах обычно менеджер проекта решает, какие пакеты визуализации используются в зависимости от его опыта. Раньше я рисовал диаграммы в MS Visio, Edraw, yed, openOffice draw, также ряд онлайн-инструментов, таких как Gliffy, Lucida Charts, Draw.io и т. Д.
Общая проблема, которую я имел — это постоянное чувство, что я бы нарисовал их намного проще с карандашом и сканировать потом. На некоторой сложной диаграмме установить еще один вопрос, который у меня было также было » Эй, как сегодня я провел свой рабочий день сегодня «так как диаграммы также должны постоянно обновляться, так как программное обеспечение развивается, иногда трудно отслеживать различия в запатентованных двоичных форматах или даже постоянно проверяют диаграммы различий в Интернете (например, Gliffy, где поддерживается версия). На некоторых проектах мы имели Google Docs с количеством версий диаграмм файлов, загруженных. Если проект использовал слияние — это было, вероятно, лучшее дело когда-либо возможно. На некоторых проектах у нас был только вики, предоставленный Bitbucket …
Довольно долгое время я искал последовательный подход, как сохранить свои диаграммы источниками как можно простыми. В основном у меня был очень базовый набор требований:
- провести минуты для проекта диаграммы
- Чтобы иметь возможность увидеть историю изменений в контроле источника
- Идеально уметь объединить диаграмму с кодом
Позвольте мне поделиться с вами текущим состоянием моих выводов:
Инструмент № 1: завод UML
Сайт: http://www.plantuml.com/
Зависимости: Java, пакет графоза
Диаграммы поддерживаются: УМЛ набор и немного больше
Инструмент способен нарисовать полный набор диаграмм UML, что делает его почти идеальным, хотя ваш продавец, вероятно, не будет счастлив от взгляда. Но для целей документации они идеальны:
Но что отличное, это то, что источники диаграмм являются чистым текстом:
Это позволяет размещать их вместе с кодом, например, в качестве блочного комментария к вашему модулю, легко отслеживать изменения в системе контроля источника и т. Д.
Инструмент имеет номер интеграции с разнообразным программным обеспечением: http://plantuml.com/running из IDE, к вики или слияние.
Вы можете попробовать интерактивно, как нарисовать диаграммы сейчас на https://www.planttext.com/ или просмотреть несколько предварительно созданных Диаграммы на http://bit.ly/plantdiag.
Инструмент № 2: BlockDiag
Сайт: http://www.blockdiag.com/
Зависимости: поддерживаются диаграммы Python 2+: блоки, последовательности, активность, сеть, стойка, структура пакетов.
Диаграмма активности, например, выглядит лучше, чем один, созданный Plantuml
По сравнению с графическими диаграммами STONTUML выглядят лучше, но минусами состоят в том, что количество вариантов намного ниже. С другой стороны, есть некоторые конкретные диаграммы, такие как структура пакетов, стойки или просто графики — которые делают этот инструмент идеальным.
Инструмент № 3: Сфинкс док
Сайт: http://www.sphinx-doc.org/ Зависимости: Python 2+
Плюсы: Универсальный, в том числе собственный заказ на заказ для создания страниц
Минусы: плагины иметь значение
Plantuml and Blockdiag — идеальные инструменты и могут использоваться самостоятельно, чтобы создать диаграмму изображения, которые вы вставляете в свои Wikis после этого.
Но если вы ищете решение для полного цикла для вашей проектной документации — посмотрите на SPHINX DOC.
Это универсальное решение, чтобы быть двигателем проектной документации для проекта любого размера, а мой конкурент с вики, слияниями и аналогичными инструментами
Выходные форматы : Html (включая html html html), латекс (для печати PDF версии), epub, texinfo, ручные страницы, простой текст
Обширные перекрестные ссылки : семантическая разметка и автоматические ссылки для Функции, классы, цитаты, глоссарий и аналогичные части информации
Иерархическая структура : Легкое определение дерева документа, с автоматическим Ссылки на братьев и сестер, родителей и детей
Автоматические показатели : Общий показатель, а также языковой модуль индексы
Обработка кода : Автоматическая подсветка с использованием Highlighter Pygments Расширения: Автоматическое тестирование фрагментов кода, включение Docstrings из Модули Python (документы API) и более
Внесенные расширения : более 50 расширений, внесенных пользователей в второй репозиторий; Большинство из них устанавливаются из Pypi
На мое скромное мнение, плюсы:
- Хорошо известный, темума
- Широкий ассортимент плагинов и расширений
- Ваши собственные пользовательские генераторы страницы
- Продвинутый синтаксис RST
В этот момент я не могу пропустить минусы, вы должны учитывать:
- Тема «readthecss»
- Вам нужно тщательно выбрать плагины
- Усилия по развитию в начале
- Путаница на Markdown — если вы используете Markdown каждый день, переключаетесь между RST и Указание будет на панели
Когда я говорю, что тема «READTHEDOCS» — это минусы — я имею в виду, что, вероятно, единственная существующая полностью адаптированная тема для документации — это тот, который вы видели сотни раз:
Документы проекта Bootstrap Boaterlate
В результате экспериментов я пришел с решением, основанным на инструментах, продемонстрированных выше. Демонстрация развернутого артефакта, вероятно, рассказывает более нескольких Пункты: http://labs.voronenko.info/projectdocs/
Github: https://github.com/voronenko/projectdocs
«Готов к работе». Конфигурация: либо в форме локальной установки (Plantuml & BlockDiag необходимо установить в системе) или через Docker (Alpine на основе небольшого следа) — это позволяет начать свой проект документации менее часа.
Интеграция с вашим кодом
Вы можете иметь выделенный репозиторий для проекта проекта проекта, если ваш проект состоит из нескольких репозиториев, или вы можете просто иметь филиал документации по объему репозитория кода проекта
Тот же источник потока
Если вы воспользуетесь Gitflow или аналогичным кодовым подходом, вы получите выгоду от того же потока в проекте документации — Pull Request, Review Code, Release …
Ноль Старт: клон и изменить
Котельная пластина включает в себя:
- Общие примеры страницы и диаграммы
- Построить процедуры
- Построить процедуры для докера
- Пакетные процедуры
- Проект развертывания для GitLab/Jenkins
Интеграция с строительным трубопроводом
Вы полностью контролируете, как и где вы создаете свой проект. Опора в котельной опоры:
- Местные сборки (бегите самостоятельно) — Упаковка и версию логики на
- Docker Build (Run с Doceerized Sphinx Environment) — для использования, например, с Gitlab.
Интеграция с развертыванием трубопровода
У вас есть полный контроль, где и как вы разверните свою документацию.
Котельная пластина поддерживает развертывание с помощью Anbible (Jenkins, Bamboo, и т. Д.) и включает в себя тянущуюся экономную игру для этого. Пример для GitLab также включен.
Публикация бонуса
Для локальной сборки решения также поддерживает такие артефакты построения, такие как MOBI, EPUB и PDF — что позволяет публиковать свою документацию в автономной форме и распространять вместе с вашим решением
Резюме
Если вам нравится подход, вы можете начать принимать его сейчас. Пожалуйста, найдите ниже базовые предметы текущей статьи в форме презентации
Оригинал: «https://www.codementor.io/@slavko/documentation-as-a-project-62pcnp93j»