Структура, стилистика, правила оформления заметок, картинок, ссылок и примеров кода

Документация является неотъемлемой частью любого успешного продукта, поэтому необходимо подходить к документированию разрабатываемых продуктов с максимальной ответственностью и своевременно актуализировать информацию.

Ниже приведены рекомендации по написанию документации для продуктов платформы Flexberry.

Документация создается с использованием генератора статических сайтов Jekyll, соответственно, необходимо иметь представление о Markdown синтаксисе для создания статей.

Правила оформления

Исходный код документации хранится в репозитории https://github.com/Flexberry/flexberry.github.io.

  • Все статьи увязаны в общую структуру статей в соответствии с наименованием продукта и его особенностями.
  • Требуется соблюдать единообразие терминов, для этого существует специальный Глоссарий.
  • Все фразы статьи строятся в обезличенной форме с использованием литературной и профессиональной лексики.

Формирование каталогов

Файлы с текстами статей распологаются в подкаталогах, по соответствующим продуктам и категориям, в каталоге pages/products и именуются по шаблону [product-prefix]_[article-name].[lang].md, где:

  • product-prefix - префикс, сокращение от названия продукта
  • article-name - название статьи на английском языке
  • lang - язык статьи, допустимые значения ru и en

Например, файл с текстом данной статьи имеет следующее имя: pages/products/flexberry-platform/work-article/fp_how-create-article.ru.md.

Скриншоты следует располагать соответственно расположению продукта (pages\products\product-name\product-catalog\product-catalog). Картинкам должны быть присвоены уникальные имена или номера, чтобы в тексте статьи можно было легко ссылаться на них. Предпочтителен формат .png.

Оглавление (sidebars)

При добавлении статьи необходимо добавить запись о ней в оглавление раздела соответствующего продукта.

Оглавления разделов описываются на языке YAML в файлах _data/sidebars/[product-name]_sidebar.yml. Запись о статье должна содержать следующую информацию:

  • title - имя ссылки на статью в оглавлении на английском языке
  • title_ru - имя ссылки на статью в оглавлении на русском языке
  • url - ссылка на статью, без указания языка, в формате /[product-prefix]_[article-name].html
  • output - форматы генерации статьи, перечисленные через запятую, допустимые значения web и pdf

Например, в файле _data/sidebars/flexberry-platform_sidebar.yml содержится следующая запись об этой статье:

# ...
    - title: Documentation writing guidelines
      title_ru: Рекомендации по написанию документации
      url: /fp_documentation-writing-guidelines.html
      output: web, pdf
# ...

Метаданные статьи

В начале каждого файла с текстом статьи должен быть расположен блок с метаданными, он окружается тремя символами тире (---), и включает следующую информацию:

  • title (название статьи). Название статьи должно быть достаточно кратким и исчерпывающим, отражающим основную суть.
  • summary (описание). Краткое описание содержания статьи должно дать понимание читателю о содержании - позволит быстро оценить, правильно ли он перешёл. Используется в индексе поиска статей.
  • sidebar (привязка к оглавлению раздела, смотрите, как указано в соседних статьях)
  • keywords (ключевые слова, заполнять через запятую - по ним работает поиск)
  • toc (добавить ли оглавление со ссылками по заголовкам (под основным меню слева), обычно true)
  • permalink - уникальная ссылка на статью, в формате [lang]/[product-prefix]_[article-name].html
  • lang - язык статьи, допустимые значения ru и en

Например, блок с метаданными для данной статьи, будет выглядеть следующим образом:

---
title: Рекомендации по написанию документации
sidebar: flexberry-platform_sidebar
summary: Рекомендации, советы, и требования, которые нужно учесть при создании статьи.
toc: true
permalink: en/fp_documentation-writing-guidelines.html
lang: en
---

Оформление содержания статьи

  • Блоки статьи начинаются со второго уровня заголовков (##). До и после заголовка следует оставить пустую строку.
  • Ссылки оформляются следующим образом: [текст](ссылка). Если фраза предполагает ссылку на несколько статей, в результате чего предложение выглядит как одна большая ссылка, то термины рекомендуется вынести в отдельный абзац. Таким образом, терминам можно будет дать краткое пояснение и ссылку на определение, не перегружая основной текст.
  • Скриншоты вставляются следующим образом ![](/images/pages/products/product-name/product-name]/image-name.png). Отделяются пустой строкой до и после скриншота (исключение составляют примеры кнопок в тексте).
  • Если на часть текста необходимо обратить особое внимание, можно добавить заметку:
  • Примеры кода отделяются пустой строкой и тремя апострофами (на букве Ё) до и после кода. Также можно указать язык примера. Язык для примеров на c# обозначается как csharp.

Полезные ссылки

Это интересно