Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documenting Your Open Source Project

Documenting Your Open Source Project

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

shedrack akintayo

October 20, 2020
Tweet

More Decks by shedrack akintayo

Other Decks in Programming

Transcript

  1. - Developer Advocate @ Cloud Foundry Foundation - Technical Writer

    for Smashing Magazine & LogRocket - Open Source Community Builder About Me.....
  2. 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
  3. 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.
  4. Forms of Documentation • Written Text(ReadME, Release Notes etc.). •

    Illustrations(roadmaps). • Videos. • Audio. • Comments in code.
  5. 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)
  6. 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
  7. 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
  8. 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.
  9. POSSIBLE STRUCTURE FOR YOUR DOCUMENTATION • Getting Started. • Architectural

    Design • In-production usage guide. • Use cases. • References • Roadmap
  10. SOME EXAMPLES OF GOOD OSS DOCS • Gatsby Docs. •

    ReactJS Docs. • VueJS Docs. • Chakra-ui Docs • Github Open API Docs • Cloud Foundry Docs • Bootstrap Docs