Skip to content

Latest commit

 

History

History
32 lines (28 loc) · 3.17 KB

docs.md

File metadata and controls

32 lines (28 loc) · 3.17 KB
Raw

Docs writing conventions

Tools

  1. To create, edit and publish articles it is recommended to use the Visual Studio Code editor with the extension packs:
  2. To manage versioning of an article, you need to install Git version control system. More information about using version control systems in Visual Studio Code can be found in the article

Styling

  1. The article should have the following structure
    • Module Name - the name of the article (corresponds to the name of the module). Styled as a first level header. An article can have only one first level heading.
    • Overview - a brief description of the module: what the module is for, what components it consists. Styled as a second level heading.
    • Functional Requirements - a description of the functional requirements of the module. If the description of the requirements is too big (contains more than 3 paragraphs), it is necessary to split the description into separate independent documents (articles). The section contains a list of names of requirements that refer to descriptions of the relevant requirements. Styled as a second level heading.
    • Scenarios - a list of scripts implemented by the module. Scenarios descriptions are made out as separate articles. Each item in the list styled as a hyperlink to the the corresponding description separate document. Styled as a second level heading.
    • Web API - link to the description of the Web API module. Styled as a second level heading.
    • Data Model - module data model diagram. Styled as a second level heading.
    • License - the current license agreement. Styled as a second level heading.
  2. Readme.md is the main file of the article. It should be in the root folder of the project.
  3. Each independent document should be released as a independent file (topic-name.md).
  4. All independent documents should be located in the \docs\ folder
  5. All drawings and diagrams should be located in the \docs\media\ folder.
  6. At the end of the article section, you must add links to:
    • parent article
    • next parent section
    • previous parent section
    • "you may also be interested"
  7. Use only Latin letters, numbers, symbols “-” for articles and graphics files naming. Use only lowercase letters for file names. Use symbols “-” instead of spaces. Example some-article.md
  8. The file name of an independent document must match the title of the article. The file for the article Add New Assignment should be named add-new-assignment.md. An exception is the main file of the article readme.md.
  9. For graphic files containing diagrams naming use the prefix diagram-. For example diagram-add-new-assignment.png.
  10. For graphic files containing examples of graphical interfaces naming use the prefix screen-. For example screen-pricing-widget.png.