These are slides for my talk at the Monthly Github Virtual Meetup Africa
- Developer Advocate @ Cloud Foundry Foundation
- Technical Writer for Smashing Magazine & LogRocket
- Open Source Community Builder
- What is Documentation?
- Importance of Docs in OSS
- Tips for Writing Effective Docs
- Traits of Successful OSS Docs
- Tools for Writing Good OSS Docs
- Possible Structure your Documentation
- Examples of Good Open Source Docs
Before we begin.....
WHAT IS DOCUMENTATION?
Documentation in programming is basically any written text,
illustration or media that gives detailed information about a
particular software. The information could include how to use
the software and/or how the software operates.
• Written Text(ReadME, Release Notes etc.).
• Comments in code.
IMPORTANCE OF DOCUMENTATION IN OSS
• It helps educate people and keep track on all aspects of
• It improves the quality of the software.
• It informs people on all changes made on the software
including version updates(release notes).
• It informs people on what aspect of the software is
currently being worked on by the maintainers of the OSS
TIPS FOR WRITING EFFECTIVE OSS DOCS
• Define a style guide for your documentation and enforce it
• Pick a markup style and stick with it
• Focus on using an active voice.
• Make use of simple and short sentences(efficient communication).
• Make sure to format your documentation properly for easy reading.
• Include sample code and examples
• Use visual devices to represent information e.g illustrations, tables, graphs etc.
• Always spell check your documentation to avoid errors.
• Provide contribution guidelines
TRAITS OF SUCCESSFUL OSS DOCS
• Easy access to information regarding core aspects of the
• Well structured.
• Help new developers learn to use the OSS quickly.
• Simplify the usage of the OSS
• Cut the amount of times users of the OSS need support
SOME TOOLS FOR WRITING
GOOD OSS DOCS
Docusaurus makes it easy
to maintain Open Source
Sphinx is what is called a
This means that it takes a
bunch of source files in plain
text, and generates a bunch
of other awesome things,
GITHUB (& GITHUB
To use GitHub for
documenting your software,
just fill the README in with
markdown. If you want more
than just one sheet of
formatted text, you can
take advantage of GitHub’s
Pages tool and you can
even route a custom domain
READ THE DOCS
Read the Docs simplifies
software documentation by
versioning, and hosting of
your docs for you.
POSSIBLE STRUCTURE FOR YOUR DOCUMENTATION
• Getting Started.
• Architectural Design
• In-production usage guide.
• Use cases.
SOME EXAMPLES OF GOOD OSS DOCS
• Gatsby Docs.
• ReactJS Docs.
• VueJS Docs.
• Chakra-ui Docs
• Github Open API Docs
• Cloud Foundry Docs
• Bootstrap Docs
REFERENCES AND RESOURCES
How to connect