DocsGuidelines

Documentation guidelines

Documentation is very important in development, because it helps developers coordinate efforts, gain knowledge, and be effective.
Treat documentation with the same responsibility as code.

Documents

Which to use and how to use them.

If you want to know where to start, or how to build, or how to translate and much more, then look at the Developers' handbook.

This is the place for code documentation - code style, architecture, patterns, etc.

When writing code documentation, it is preferred that the writer create new directories for new sections and new files for separate topics so that the documentation structure is clear and one aspect is described in each file. Each directory (section) must contain a README.md file, which is the root of this section.

Text

For writing documentation we use standard markdown syntax (see Markdown Cheatsheet)
You can write markdown text in any text editor, in addition, you can use useful tools, for example: VS Code + markdownlint + Github Markdown Preview

Diagrams

For creating diagrams we use draw.io
To add a diagram, you need to export the diagram in two formats:

• XML (not compresed) - used to store the original diagram so that we can edit it in the future. The diagram should be in uncompressed xml format in order to be able to resolve conflicts.
• PNG - used to view the diagram in the documentation.

The name of both files should be the same and contain the suffix .drawio. For example:

some_name.drawio.xml
some_name.drawio.png

Markdown Cheatsheet

This file provides a quick tour to start writing markdown.

For further details, please reference here

Headers

# H1
## H2
### H3

or

Alt-H1
======

or

Alt-H2
------

Emphasis

You can emphatize a portion of text in different ways. 

You can use *italics* enclosing one or _more words_ within * or _. 
You can also make it **bold** with double * or _. 

You can combine them enclosing more _ or * into ** or __, for example 
**_This is both bold and italic_**. 

Lists

1. I'm the first item of an ordered list
2. And I'm the second one

* I'm an unordered list, you can define that using * (asterisk), + (plus) or - (minus)
* (Watch out, the second item must be attached to first one if you use * to define the list)

Links

[I'm a link to google](https://www.google.com)
[I'm a relative reference to a repository file](../blob/master/LICENSE)

Images

![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

or 

![alt text][logo]
[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

Code and syntax highlighting

Inline `code` has `back-ticks around` it.

You can also define blocks of code using three backticks

Footnotes

Here is a simple footnote[^1].

[^1]: My reference.

Tables

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Blockquote

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.