Structure, style, rules, registration of notes, images, links, and code examples

Documentation is an integral part of any successful product, so you need to approach the documentation of developed products with the utmost responsibility and to promptly update the information.

The following are guidelines for writing documentation for platform products Flexberry.

Documentation is generated using the generator of static sites Jekyll and therefore needs to have an idea about Markdown syntax to create articles.

design Rules

Source code documentation stored in the repository https://github.com/Flexberry/flexberry.github.io.

  • All articles are linked to the overall structure of articles in accordance with the name of the product and its features.
  • Required to observe the consistency of terminology, for this there is a special Glossary.
  • All phrases the articles are constructed in anonymously with the literature and professional vocabulary.

directories

The file with the texts of articles are placed in subdirectories, sootvetstvuyuschim products and categories in the directory pages/products, and are named according to the pattern [product-prefix]_[article-name].[lang].md where:

  • product-prefix prefix, the abbreviation of the product
  • article-name the title of the article in English
  • lang - language articles, valid values are ru and en

For example, a file with the text of the article has the following name: pages/products/flexberry-platform/work-article/fp_how-create-article.EN.md.

The screenshots should be placed according to the placement of the product (pages\products\product-name\product-catalog\product-catalog). The pictures must be assigned unique names or numbers to the text of the article could easily refer to them. The preferred format .png.

table of contents (sidebars)

When adding an article, you need to add an entry for it in the contents section of the relevant product.

Table of contents sections are described in the language of YAML in the file _data/sidebars/[product name]_sidebar.yml. The article should contain the following information:

  • title - the name links to the article in the table of contents in English
  • title_ru - the name links to the article in the table of contents in Russian
  • url - link to the article, without specifying the language, format, _/[product-prefix]_[article-name].HTML
  • output formats generation of article, comma-separated, valid values web and pdf

For example, in the file _data/sidebars/flexberry-platform_sidebar.yml contains the following entry about this article:

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

Metadata article

At the beginning of each file with the text of the article should be a block with metadata, it is surrounded by three characters dash (---), and include the following information:

  • title (name of article). Title of the article should be fairly concise and comprehensive, reflecting the main thrust.
  • summary (description). Brief description of the content of the article should give understanding to the reader about the content - will allow you to quickly assess whether he passed. Use the index to search for articles.
  • sidebar (linked to table of contents section, see as indicated in the adjoining articles)
  • keywords (keywords, fill in a comma - search)
  • toc (to add a table of contents with links in the headers (under the main menu on the left), usually true)
  • permalink is a unique link to the article in format _[lang]/[product-prefix]_[article-name].HTML
  • lang - language articles, valid values are ru and en

For example, a block with metadata for the article, will link as follows:

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

Making the content of the article

  • Blocks articles begin with second level header (##). Before and after the title should leave a blank line.
  • References are made in the following way: [text](link). If the phrase includes a link to a few articles in resultate what the offer looks like one big link, the terms are recommended to be put in a separate paragraph. Therefore, the terms can be given a brief explanation and a link to the definition without overloading a main text.
  • Screenshots are inserted in the following way ![](/images/pages/products/product-name/product-name]/image-name.png). Separated by a blank line before and after screenshot (with the exception of examples of the buttons in the text).
  • If the text part need to pay special attention, you can add note:
  • Code examples are separated by a blank line and three apostrophes before and after the code. You can also specify language Primera. The language for the examples on the c# referred to as csharp.

It’s interesting