Documenting Your Open Source Project

These are slides for my talk at the Monthly Github Virtual Meetup Africa

Transcript

1. Documenting Your Open Source Project Shedrack Akintayo
2. - Developer Advocate @ Cloud Foundry Foundation - Technical Writer for Smashing Magazine & LogRocket - Open Source Community Builder About Me.....
3. What We'll Discuss TOPIC OUTLINE - 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
4. Before we begin.....
5. 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.
6. Forms of Documentation • Written Text(ReadME, Release Notes etc.). • Illustrations(roadmaps). • Videos. • Audio. • Comments in code.
7. IMPORTANCE OF DOCUMENTATION IN OSS • It helps educate people and keep track on all aspects of the software. • 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 projects (roadmaps)
8. 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
9. TRAITS OF SUCCESSFUL OSS DOCS • Easy access to information regarding core aspects of the software. • 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
10. SOME TOOLS FOR WRITING GOOD OSS DOCS DOCUSAURUS Docusaurus makes it easy to maintain Open Source documentation websites SPHINX Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML GITHUB (& GITHUB PAGES) 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 to it). READ THE DOCS Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.
11. POSSIBLE STRUCTURE FOR YOUR DOCUMENTATION • Getting Started. • Architectural Design • In-production usage guide. • Use cases. • References • Roadmap
12. SOME EXAMPLES OF GOOD OSS DOCS • Gatsby Docs. • ReactJS Docs. • VueJS Docs. • Chakra-ui Docs • Github Open API Docs • Cloud Foundry Docs • Bootstrap Docs
14. REFERENCES AND RESOURCES • https://opensource.com/business/15/7/10-tips-better-documentation. • https://opensource.com/article/20/3/documentation. • https://gist.github.com/rbowen/27ca79c69dd91be6b0e3. • https://opensource.googleblog.com/2018/10/building-great-open- source-documentation.html.
15. TWITTER @coder_blvck GITHUB hackivist123 EMAIL akintayoshedrack@gmail.com Thank You How to connect with me?