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
   

   View Slide

2. - Developer Advocate @ Cloud Foundry Foundation
   - Technical Writer for Smashing Magazine & LogRocket
   - Open Source Community Builder
   About Me.....
   

   View Slide

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
   

   View Slide

4. Before we begin.....
   

   View Slide

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.
   

   View Slide

6. Forms of
   Documentation
   • Written Text(ReadME, Release Notes etc.).
   • Illustrations(roadmaps).
   • Videos.
   • Audio.
   • Comments in code.
   

   View Slide

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)
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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.
    

    View Slide

11. POSSIBLE STRUCTURE FOR YOUR DOCUMENTATION
    • Getting Started.
    • Architectural Design
    • In-production usage guide.
    • Use cases.
    • References
    • Roadmap
    

    View Slide

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
    

    View Slide

13. View Slide

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.
    

    View Slide

15. TWITTER
    @coder_blvck
    GITHUB
    hackivist123
    EMAIL
    akintayoshedrack@gmail.com
    Thank You
    How to connect
    with me?
    

    View Slide