Doc for writing brief and useful docs

[robrap]

A Quick Reference on writing docs would be helpful, especially in response to docs with lots of paragraphs.

Here are a number of resources that could be summarized and consolidated into a single doc:

• https://f.hubspotusercontent00.net/hubfs/1658400/White_Papers/5%20tips%20for%20succeeding%20with%20plain%20langauge.pdf
• https://informationmapping.com/blogs/news/conquering-documentation-debt
• https://informationmapping.com/blogs/news/the-information-mapping-format-a-proven-content-standard
• https://informationmapping.com/blogs/news/getting-non-writers-to-create-usable-documentation-5-essentials-for-success
• https://informationmapping.com/blogs/news/fun-facts-about-information-mapping
• https://informationmapping.com/blogs/news/information-mapping-avoiding-the-3-most-common-mapping-mistakes
• https://informationmapping.com/blogs/news/nobody-wants-to-read-what-you-write

This was a note-to-self, but I never seem to get to this, so I am sharing as a github issue in case someone ever wants to take this up instead. Additionally, even this list alone may help someone.

[jswope00]

This doc was created in late 2024. Covers many principles of good docs in the Open edX docs repo: https://docs.openedx.org/en/latest/documentors/references/doc_style_guide.html

[robrap]

That’s great. Thank you. That fulfills my wish, so I’ll close this issue.