info/the-documentation-compendium
1
0
Fork 0
mirror of https://github.com/kylelobo/The-Documentation-Compendium.git synced 2025-09-19 09:11:27 +02:00
Code Issues Releases Wiki Activity

Added emojis, updated tech writing sources, programs

Browse Source
This commit is contained in:
Kyle Lobo
2019-06-05 00:53:34 +05:30
committed by GitHub
parent ef133dac84
commit d965fbbd15
1 changed files with 27 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@@ -3,11 +3,11 @@
![Documentation](https://i.imgur.com/rSyq3MW.png)
<p align = "center">Good documentation is key to the success of any project. Making documentation accessible enables people to learn about a project; helping them to save time while reading / contributing to a project.</p>
<p align = "center">💡 Good documentation is key to the success of any project. Making documentation accessible enables people to learn about a project; helping them to save time while reading / contributing to a project.</p>
</div>
## Table of Contents
## 📝 Table of Contents
+ [Why must you document your project](#why_document)
+ [The DO's and DON'Ts of Documentation](#dos_and_donts)
+ [Templates](https://github.com/kylelobo/The-Documentation-Compendium/tree/master/Templates)
@@ -16,37 +16,41 @@
+ [API Documentation](https://www.writethedocs.org/guide/#api-documentation)
+ [Tools](https://www.writethedocs.org/guide/#tools-of-the-trade)
+ [Technical Writer Programs](#programs)
+ [Awesome Technical Writing Articles](#articles)
+ [Awesome Technical Writing Sources](#sources)
+ [References](#references)
## Why must you document your project?<a name = "why_document"></a>
+ You will be using your code in 6 months. Code that you wrote 6 months ago is often indistinguishable from code that someone else has written
+ You want people to use your code because you think that others might find it useful. However, people need to understand why your code might be useful for them, before they decide to use it
+ You want people to help out. If you don’t have documentation, you will miss out on a whole class of contributors.
+ You want to be a better writer
## 🤔 Why must you document your project?<a name = "why_document"></a>
+ **THE MAJORITY OF PEOPLE GLANCE AND LEAVE.** Make it pretty so that it's easier for them to star before they leave. The more stars you have, the likelier it is that serious developers will use your repo.
+ You will be using your code in _6 months_. Code that you wrote 6 months ago is often indistinguishable from code that someone else has written
+ You want people to use your code because you think that others might find it useful. However, people need to _understand why_ your code might be useful for them, before they decide to use it
+ You want people to _help out_. If you don’t have documentation, you will _miss out_ on a whole class of contributors.
+ You want to be a _better_ writer
## The DO's and DON'Ts of Documentation<a name = "dos_and_donts"></a>
DO'S:
+ Keep a lighthearted friendly tone. Treat the reader as a close friend who doesn't have a lot of knowledge about the topic but is very interested
+ Keep things brief
+ Use headings frequently. This breaks things up when reading and often it is good for linking to specific information
+ Link to other places in the documentation often but only for additional information. Readers should not have to navigate through several pages to find the information that they need about one specific thing. Just inline the immediately relevant information and link off if they want to know more
## 🚦 The DO's and DON'Ts of Documentation<a name = "dos_and_donts"></a>
**✔️ DO'S:**
+ Keep a lighthearted friendly tone. Treat the reader as someone who doesn't have a lot of _knowledge_ about the topic but is very interested
+ Keep things _brief_
+ Use _headings_ frequently. This breaks things up when reading and often it is good for linking to specific information
+ Link to other places in the documentation often but only for additional information. Readers should not have to navigate through several pages to find the information that they need about _one specific thing_. Just _inline_ the immediately relevant information and link off if they want to know more
+ Use as many code snippets, CLI, etc. examples as possible. Show the reader what you mean
+ Gently introduce a guide before diving into technical details. This gives context and readers are more likely to stay engaged longer
+ Gently _introduce a guide_ before diving into technical details. This gives context and readers are more likely to stay engaged longer
+ It is always good to describe the functionality of the various files in your project
DON'TS:
+ Don't assume prior knowledge about the topic. If you want to appeal to a large audience, then you are going to have people with very diverse backgrounds
+ Don't use idioms. Speak using more formal terms that are well defined. This makes it easier for non-native English speakers and for translations to be written
**❌ DON'TS:**
+ Don't assume _prior knowledge_ about the topic. If you want to appeal to a large audience, then you are going to have people with very diverse backgrounds
+ Don't use _idioms_. Speak using more formal terms that are well defined. This makes it easier for non-native English speakers and for translations to be written
+ Don't clutter explanations with overly detailed examples
+ Use terms that are offensive to any group. There will never be a good reason to
+ Use terms that are _offensive_ to any group. There will never be a good reason to
## Technical Writing Programs <a name = "programs"></a>
## 👨‍💻 Technical Writing Programs <a name = "programs"></a>
1. [A List of Open Source Projects with Volunteer Documentation Opportunities](https://www.reddit.com/r/technicalwriting/comments/800a9a/a_list_of_open_source_projects_with_volunteer/)
## Awesome Technical Writing Articles <a name = "articles"></a>
1. [My Tech Writing Process - Amruta Ranade](https://amrutaranade.com/2018/03/07/my-writing-process/)
## 🎉 Awesome Technical Writing Sources <a name = "sources"></a>
1. [r/technicalwriting](https://www.reddit.com/r/technicalwriting/)
2. [My Tech Writing Process - Amruta Ranade](https://amrutaranade.com/2018/03/07/my-writing-process/)
3. [Developer to Technical Writer](https://www.reddit.com/r/technicalwriting/comments/a1x6c8/)
## References <a name = "references"></a>
## 📚 References <a name = "references"></a>
1. [Documenting your projects on GitHub by GitHub Guides](https://guides.github.com/features/wikis/)
2. [documentation-handbook by jamiebuilds](https://github.com/jamiebuilds/documentation-handbook)
3. [Documentation Guide by Write the Docs](https://www.writethedocs.org/guide/)