Refactor documentation to markdown

[bruno-f-cruz]

This PR refactors the main documentation documents of the Harp protocol to use markdown instead of docx.

This will also facilitate keep tracking of versions, so my suggestion would be to only store the markdown files and, when a release is made, attach the corresponding pdfs (which can be easily automatically generated) to the release files.

As a side note, I am not fully satisfied with the way GitHub renders Mermaid gantt plots. While it works nicely when rendering it using my VSCode plugin, github rendered does not allow the compact mode, leading bars to offset. We might want to converge on a general solution to generate these diagrams (e.g. bit maps).

[artursilva0]

This PR refactors the main documentation documents of the Harp protocol to use markdown instead of docx.

This will also facilitate keep tracking of versions, so my suggestion would be to only store the markdown files and, when a release is made, attach the corresponding pdfs (which can be easily automatically generated) to the release files.

As a side note, I am not fully satisfied with the way GitHub renders Mermaid gantt plots. While it works nicely when rendering it using my VSCode plugin, github rendered does not allow the compact mode, leading bars to offset. We might want to converge on a general solution to generate these diagrams (e.g. bit maps).

I also don't like the way those plots were generated. They are not very clear unfortunately. What do you mean by bit maps?

[bruno-f-cruz]

This PR refactors the main documentation documents of the Harp protocol to use markdown instead of docx. This will also facilitate keep tracking of versions, so my suggestion would be to only store the markdown files and, when a release is made, attach the corresponding pdfs (which can be easily automatically generated) to the release files. As a side note, I am not fully satisfied with the way GitHub renders Mermaid gantt plots. While it works nicely when rendering it using my VSCode plugin, github rendered does not allow the compact mode, leading bars to offset. We might want to converge on a general solution to generate these diagrams (e.g. bit maps).

I also don't like the way those plots were generated. They are not very clear unfortunately. What do you mean by bit maps?

bit maps = the maps that describe what each one of the bits represent.

Ye I am not super happy with them either, but the alternatives were not clearly better. HTML is way less readable; Markdown tables are too limited; SVGs look nicer but you need additional software to draw them and you need to save them as assets

Do you have a suggestion?

[artursilva0]

Personally I prefer the .svg option since it's the only one that will be capable of generating any sort of diagrams that might necessary in the future. Let's see what the other reviewers think about that.

[artursilva0]

Personally I prefer the .svg option since it's the only one that will be capable of generating any sort of diagrams that might necessary in the future. Let's see what the other reviewers think about that.

After our offline discussion, I've tried to implement a raw example of a CSS + HTML code inside an SVG, that can be rendered inside GitHub markdown. One of the disadvantages is that you'll still need to generate the SVGs as assets. Example here: https://github.com/artursilva0/harp-protocol/blob/docs-to-md/Device.md#r_operation_ctrl-u16--operation-mode-configuration

Nevertheless, taking into account that the way the GitHub is rendering these plots, may be changed in the Harp website (different CSS) and that the PDFs generated present a much more appealing Gantt plot, I'm ok in keeping this as it is.