Different markdown syntax in documentation

Feedback
1

Is there a reason for the difference in the way headings are marked in the documentation?

Example:

  1. User / Advanced topics / Config files:
    Qubes-specific VM config files
------------------------------
  2. User / Hardware / System requirements:
    ## Minimum

If this is unintentional, I assume that atx-style (# ) shall be preferred?

2

Both are valid syntax. Some folks prefer one over the other, as they read slightly differently in plain text (when the Markdown is not rendered as HTML) and in Git diff files.

As far as I know, there is not official guideline, so you can use whichever you want when writing docs. (And if you ask me, there are many aspects of writing docs worth agreeing upon before spending time debating header syntax in a guideline, so I would really not worry about it! YMMV)

1 Like
3

Yeah, but # allows more levels

Cool, thanks.

For some reason I made an assumption that more important aspects are due to discussion in a pull request.

4

One more note in addition to information provided by @gonzalo-bulnes. There are more than two. For example Github supports many.

Similarly, most of them could be converted to a manpage.

For personal use, it would be your own choice. For contribution to other projects (e.g. Qubes OS CLI manuals), my advise is to continue using the existing format in target repository (usually reStructuredText, Setext, troff, …). Fortunately learning most those formats is pretty easy.

5

Not talking about different formats here @alimirjamali, only different syntax for Markdown. Makes sense? (That doesn’t remove anything to what you said, only that I think syntax in this case is inconsequential.)

2 Likes
6
  1. The convention changed from one style to the other at one point.
  2. Different contributors sometimes use different styles.

There is:

https://www.qubes-os.org/doc/documentation-style-guide/#headings

3 Likes