AsciiDoc

Problem

Problem

Программное обеспечение обычно сопровождается документацией:

  • Документацию пишут и поддерживают технические писатели

  • Иногда документацию пишут и другие, если к документации не выставлены жесткие требования

  • Для разработки и публикации используются специализированные проприетарные инструменты, такие как Adobe RoboHelp и т.д. Иногда — Wiki и Confluence.

  • Иногда используют более простой инструментарий, с дальнейшим экспортом в конечный формат (например: PDF), и добавляют ее к продукту.

Problem

Так, а в чем проблема?

  • Отсутствие интереса к документации у большинства членов команды.

  • Трудно поддерживать.

  • Документация "протухает", т.е. не соответствует написанному.

Solution

Solution

Docs as Code

  • Документация пишется на языке разметки (например: Asciidoc, Markdown).

  • Документация хранится в Git-репозитории.

  • Документация собирается в нужный формат при помощи генератора. Форматов может быть сразу много: HTML, PDF, DOCX и так далее.

  • Документация пишется и обновляется в процессе разработки.

AsciiDoc

AsciiDoc

  • AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation.

  • AsciiDoc is a trademark of the Eclipse Foundation, Inc.

  • Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc to HTML5, DocBook and more.

AsciiDoc

Используется для написания:

  • документации

  • статей

  • книг

  • слайдов

  • веб-сайтов

  • и т.д.

Quick Guide

Headers

= Уровень 1
== Уровень 2
=== Уровень 3
==== Уровень 4
===== Уровень 5

Text

normal, 'italic', _italic_, *bold*, `mono`.

+mono *bold*+, `mono pass thru *bold*`

''double quoted'', 'single quoted'.

normal, ^super^, ~sub~.

Unordered list

* уровень 1
** уровень 2
** уровень 2
*** уровень 3
*** уровень 3
**** уровень 4
**** уровень 4
***** уровень 5

Ordered List

1. Арабские числа (1, 2, 3, 4,...)
2. Арабские числа (1, 2, 3, 4,...)
3. Арабские числа (1, 2, 3, 4,...)
4. Арабские числа (1, 2, 3, 4,...)
    a. Строчные латинские буквы (a, b, c, d,...)
    b. Строчные латинские буквы (a, b, c, d,...)

Code Blocks

----
*Листинговый* блок

Используется для листинг (кода или файла)
----

Code Blocks

[source, java]
----
// Блок с *исходным кодом*
// Используется для выделения команд для конкретного языка

public class HellToWorld {
    public static void main(String[] args) {
        System.out.println("Hell to World!");
    }
}
----

Links

link:../common/intro.adoc[Родительский документ для этого документа]
link:../common/intro.adoc[]
http://google.com
http://google.com[Google Search]
mailto:root@localhost[email admin]

Images

image::home.png[]
image::home.png[Aльтернативный текст]

Tables

[options="header"]
|===
|Столбец 1|Столбец 2|Столбец 3
|1|Содержимое 1|a
|2|Содержимое 2|b
|3|Содержимое 3|c
|===

Descriptions

.Блок с изображением
image::home.png[]

.Необязательное заглавие
----
*Листинговый* блок

Используется для листинг (кода или файла)
----