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. 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
    [email protected]
    Thank You
    How to connect
    with me?

    View Slide