In my experience, documentation is as important to the final product as code. Keeping both in sync is much easier when both a stored in the same repository and can therefore also be reviewed with the same tools (pull requests as code review).
Personally, I like working with Markdown for short documents (e.g. READMEs) and Sphinx/RestructuredText or Asciidoc for large documentation bodies like handbooks, guides, references, and so on.
For all of them there’s also strong tooling support available which helps you, for instance, to do automated spell- or link-checking.
I hope this helps and gives you some ideas for your projects 🙂
This indeed helps me a lot. If you don't mind the question, why do you prefer Markdown for short documents? Is there a lack of functionality that makes it unsuitable for large documents?
That’s pretty much it. Markdown itself only supports basic markup like bold, italic and linking, but if you, for instance, want to mark things like keyboard shortcuts, menu entries etc. (which is quite common in manuals and userguides), Asciidoc and Sphinx offer far more.
The technical term for the feature I’m referring to is “semantic markup”. For manuals etc. this is essential.
Markdown, on the other hand, has ether advantage that it is far more common, so onboarding new people is easier.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
In my experience, documentation is as important to the final product as code. Keeping both in sync is much easier when both a stored in the same repository and can therefore also be reviewed with the same tools (pull requests as code review).
Personally, I like working with Markdown for short documents (e.g. READMEs) and Sphinx/RestructuredText or Asciidoc for large documentation bodies like handbooks, guides, references, and so on.
For all of them there’s also strong tooling support available which helps you, for instance, to do automated spell- or link-checking.
I hope this helps and gives you some ideas for your projects 🙂
This indeed helps me a lot. If you don't mind the question, why do you prefer Markdown for short documents? Is there a lack of functionality that makes it unsuitable for large documents?
Saludos,
That’s pretty much it. Markdown itself only supports basic markup like bold, italic and linking, but if you, for instance, want to mark things like keyboard shortcuts, menu entries etc. (which is quite common in manuals and userguides), Asciidoc and Sphinx offer far more.
The technical term for the feature I’m referring to is “semantic markup”. For manuals etc. this is essential.
Markdown, on the other hand, has ether advantage that it is far more common, so onboarding new people is easier.