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.
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.
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-prefixprefix, the abbreviation of the product
article-namethe 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
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
outputformats 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 # ...
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
permalinkis 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
- Quick guide to Markdown.
- Linter - indicates that a formatting error in style
- Doc Jekyll Theme which we use for documentation.
- GitHowTo - interactive tour of the capabilities of the git.
- GitHub Help - help with git.
- Open issues in the repository with the documentation.
- 7 of the rules of writing technical documentation world-class - interesting article, but it is necessary to consider specificity of audience for which written or another article. That will be favorably perceived by beginners (section Practical guide) with high probability will lead to confusion for the professional (article about platform products Flexberry).
- Writing technical documentation: a guide for the layman - have described the process of creating the documentation, this valuable tips on creating an “enabling environment”, not while slipping to journalism.