Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

DotNetRu
October 18, 2018

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

Каждый разработчик сталкивается с проблемами документирования приложений для конечных пользователей или других программистов: выбор среды для документирования, выбор формата хранения документации, быстрое получение нужных выходных форматов, поддержка контроля версий для командной разработки, возможность перевода на другие языки. В докладе будет рассказано про существующие системы документирования, рассмотрены их плюсы и минусы, сделан обзор форматов хранения документации, предложен формат Markdown, как наиболее удобный для написания и хранения документации. Доклад будет интересен программистам, которые хотят писать ХОРОШУЮ документацию, полезную как для конечных пользователей так и для других программистов и техническим писателям.

DotNetRu

October 18, 2018
Tweet

More Decks by DotNetRu

Other Decks in Programming

Transcript

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

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

    – Хелп — описание функций и API – Комментарии по коду – И т.д. 4
  3. Пользовательская документация ▪ Пишется сразу после добавления нового функционала ▪

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

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

    – это дорого ▪ Хранить документацию у одного человека небезопасно ▪ Где писать документацию? ▪ Документация устаревает 7
  6. Документация нужна! ▪ Для разработчиков ▪ Для пользователей ▪ Отчетность

    перед руководством Программист, как ёжик в тумане! 8
  7. Хорошая документация ▪ Несколько языков, как минимум, документация на английском

    ▪ Понятность, документация на доступном языке ▪ Актуальность ▪ Иллюстрации ▪ Примеры 9
  8. Программы для документирования: Notepad Плюсы: ▪ Не нужно дополнительное ПО

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

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

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

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

    доку ▪ Выбор среды документирования ▪ Несколько языков, минимум английский ▪ Наличие картинок ▪ Получение PDF, HTML и т.д. 14
  13. Darwin Information Typing Architecture Это модель для – документирования –

    хранения – написания – распространения документации в html, pdf и т.д. 15
  14. 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
  15. Markdown – облегчённый язык разметки # Hello World This is

    content converted from Markdown! Here's a JSON sample: ```json { "foo": "bar" } ``` 20
  16. Документирование и Markdown ▪ Модель DITA ▪ Язык разметки Markdown

    ▪ Структура каталогов и документов ▪ Документация храниться рядом с проектом в GIT ▪ Утилиты для компиляции нескольких Markdown документов в одну общую документацию ▪ Техпроцесс написания документации 21
  17. Структура документации Русская документация Markdown документы Картинки Английская документация Markdown

    документы Картинки ▪ Общая структура на нескольких языках ▪ Один документ — значит один топик ▪ Локализованные иллюстрации ▪ Модульность 22
  18. Компиляция документации ▪ GitBook –можно документировать и публиковать документацию в

    pdf и др. ▪ Pandoc – можно конвертировать markdown в pdf, кстати, не только markdown и не только pdf ▪ Read the Docs – можно документировать и публиковать документаци в html и др. ▪ DocumentSprint – можно собирать документацию в html и pdf 23
  19. Процесс написания документации 1. Определим язык по умолчанию 2. Спроектировать

    структуру документации заранее 3. Скрипт компиляции 4. Приступить к документированию 5. Повторить с пункта №4 24
  20. Что в итоге? ▪ Документация на понятном и простом синтаксисе

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