Виталий Езепчук "Документируй меня полностью. Markdown и системы документирования"

ДОКУМЕНТИРУЙ МЕНЯ ПОЛНОСТЬЮ MARKDOWN И СИСТЕМЫ ДОКУМЕНТИРОВАНИЯ Виталий Езепчук Старший
программист Fast Reports [email protected]

Что такое документирование? Документирование Разработка 2

Архитектурная документация ▪ Пишется заранее ▪ Сюда входит: – Используемые
технологии – Библиотеки – Среда разработки – И т.д. ▪ Например, README рядом с проектом 3

Техническая документация ▪ Пишется одновременно с кодом ▪ Сюда входит:
– Хелп — описание функций и API – Комментарии по коду – И т.д. 4

Пользовательская документация ▪ Пишется сразу после добавления нового функционала ▪
Сюда входит: – Описание пользовательского интерфейса – Иллюстрации, примеры, уроки – И т.д. ▪ Уходит в продакшн 5

Маркетинговая документация ▪ Пишется после каждого релиза ▪ Сюда входит:
– Список возможностей – Рекламные материалы – Сравнение с конкурентами – И т.д. ▪ Например, Changelog 6

Проблемы документирования ▪ Программисты ненавидят писать документацию ▪ Технические писатели
– это дорого ▪ Хранить документацию у одного человека небезопасно ▪ Где писать документацию? ▪ Документация устаревает 7

Документация нужна! ▪ Для разработчиков ▪ Для пользователей ▪ Отчетность
перед руководством Программист, как ёжик в тумане! 8

Хорошая документация ▪ Несколько языков, как минимум, документация на английском
▪ Понятность, документация на доступном языке ▪ Актуальность ▪ Иллюстрации ▪ Примеры 9

Программы для документирования: Notepad Плюсы: ▪ Не нужно дополнительное ПО
▪ Редактировать и хранить где угодно, например, GIT Минусы: ▪ Это просто текст ▪ Плохо для неразработчиков 10

Программы для документирования: Word Плюсы: ▪ Удобно Минусы: ▪ Сложно
сделать общую pdf, из нескольких файлов ▪ Нельзя хранить в GIT ▪ Поддержка нескольких языков 11

Программы для документирования: Word??! «Плюсы» ▪ Удобно? Попробуй отформатируй 1500
страниц Минусы: ▪ Сложно сделать общую pdf, из нескольких файлов ▪ Нельзя хранить в GIT ▪ Поддержка нескольких языков 12

Программы для документирования: Системы документирования Плюсы: ▪ Удобно и круто
▪ Всё включено Минусы: ▪ От $500 на каждого автора ▪ GIT и другие плюшки за отдельную плату 13 ▪ Help&Manual ▪ HelpNDoc ▪ MadCap Flare ▪ Adobe RoboHelp ▪ И ещё очень много

Проблемы документирования ▪ Документация устаревает ▪ Программисты не любят писать
доку ▪ Выбор среды документирования ▪ Несколько языков, минимум английский ▪ Наличие картинок ▪ Получение PDF, HTML и т.д. 14

Darwin Information Typing Architecture Это модель для – документирования –
хранения – написания – распространения документации в html, pdf и т.д. 15

DITA – принцип единого источника Пользовательская документация Техническая документация Архитектурная
документация Маркетинговая документация Исходники документации 16

DITA – топик-ориентированный подход Заголовок Текст Ссылки 17

DITA – отделение содержимого от форматирования 18

DITA – синтаксис <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE topic PUBLIC "-//OASIS//DTD
DITA Topic//EN" "topic.dtd"> <topic xml:lang="en" id="sample"> <title>Sample</title> <body> <p audience="foo">Hello World!</p> </body> </topic> 19

Markdown – облегчённый язык разметки # Hello World This is
content converted from Markdown! Here's a JSON sample: ```json { "foo": "bar" } ``` 20

Документирование и Markdown ▪ Модель DITA ▪ Язык разметки Markdown
▪ Структура каталогов и документов ▪ Документация храниться рядом с проектом в GIT ▪ Утилиты для компиляции нескольких Markdown документов в одну общую документацию ▪ Техпроцесс написания документации 21

Структура документации Русская документация Markdown документы Картинки Английская документация Markdown
документы Картинки ▪ Общая структура на нескольких языках ▪ Один документ — значит один топик ▪ Локализованные иллюстрации ▪ Модульность 22

Компиляция документации ▪ GitBook –можно документировать и публиковать документацию в
pdf и др. ▪ Pandoc – можно конвертировать markdown в pdf, кстати, не только markdown и не только pdf ▪ Read the Docs – можно документировать и публиковать документаци в html и др. ▪ DocumentSprint – можно собирать документацию в html и pdf 23

Процесс написания документации 1. Определим язык по умолчанию 2. Спроектировать
структуру документации заранее 3. Скрипт компиляции 4. Приступить к документированию 5. Повторить с пункта №4 24

Документирование в команде 25 Master Develop Feature Documentation v0.1 v0.2
v1.0

Что в итоге? ▪ Документация на понятном и простом синтаксисе
Markdown ▪ Можно использовать любой контроль версий ▪ Для редактирования подойдёт любой текстовый редактор ▪ Принцип единого источника – один общий набор документов на несколько документаций ▪ Можно получить pdf или статичный html ▪ И главное, это удобно! 26

ВОПРОСЫ Виталий Езепчук Старший программист Fast Reports Автор DocumentSprint Witaly_Ezepchuk
[email protected]

Виталий Езепчук "Документируй меня полностью. M...

Виталий Езепчук "Документируй меня полностью. Markdown и системы документирования"

DotNetRu

More Decks by DotNetRu

Other Decks in Programming

Featured

Transcript

ДОКУМЕНТИРУЙ МЕНЯ ПОЛНОСТЬЮ MARKDOWN И СИСТЕМЫ ДОКУМЕНТИРОВАНИЯ Виталий Езепчук Старший

Что такое документирование? Документирование Разработка 2

Архитектурная документация ▪ Пишется заранее ▪ Сюда входит: – Используемые

Техническая документация ▪ Пишется одновременно с кодом ▪ Сюда входит:

Пользовательская документация ▪ Пишется сразу после добавления нового функционала ▪

Маркетинговая документация ▪ Пишется после каждого релиза ▪ Сюда входит:

Проблемы документирования ▪ Программисты ненавидят писать документацию ▪ Технические писатели

Документация нужна! ▪ Для разработчиков ▪ Для пользователей ▪ Отчетность

Хорошая документация ▪ Несколько языков, как минимум, документация на английском

Программы для документирования: Notepad Плюсы: ▪ Не нужно дополнительное ПО

Программы для документирования: Word Плюсы: ▪ Удобно Минусы: ▪ Сложно

Программы для документирования: Word??! «Плюсы» ▪ Удобно? Попробуй отформатируй 1500

Программы для документирования: Системы документирования Плюсы: ▪ Удобно и круто

Проблемы документирования ▪ Документация устаревает ▪ Программисты не любят писать

Darwin Information Typing Architecture Это модель для – документирования –

DITA – принцип единого источника Пользовательская документация Техническая документация Архитектурная

DITA – топик-ориентированный подход Заголовок Текст Ссылки 17

DITA – отделение содержимого от форматирования 18

DITA – синтаксис <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE topic PUBLIC "-//OASIS//DTD

Markdown – облегчённый язык разметки # Hello World This is

Документирование и Markdown ▪ Модель DITA ▪ Язык разметки Markdown

Структура документации Русская документация Markdown документы Картинки Английская документация Markdown

Компиляция документации ▪ GitBook –можно документировать и публиковать документацию в

Процесс написания документации 1. Определим язык по умолчанию 2. Спроектировать

Документирование в команде 25 Master Develop Feature Documentation v0.1 v0.2

Что в итоге? ▪ Документация на понятном и простом синтаксисе

ВОПРОСЫ Виталий Езепчук Старший программист Fast Reports Автор DocumentSprint Witaly_Ezepchuk