Skip to content
This repository has been archived by the owner on Mar 22, 2022. It is now read-only.

Latest commit

 

History

History
99 lines (94 loc) · 3.47 KB

sustain-belgium-notes.md

File metadata and controls

99 lines (94 loc) · 3.47 KB
Raw

Good Docs – How to Build Them (templates, best practices, checklists for good documentation)

Facilitator(s): Pia
Note taker(s): B. Norberg

Notes:

  • Goal for the session is to establish best practices for good docs
  • Let’s start with identifying who we are writing the docs for. What are the different audience personas for docs? Who is reading docs?
    • List of items on sticky notes:
      • Beginners
      • Employees doing their job
      • Developers
      • Contributors
      • Users of the software
      • Sponsors
      • Designers
      • Other documentarians
      • Earth
      • Search engines
  • It is very hard to write for beginners, but how could it be easy?
  • What should we ask ourselves when we write documentation? What do the readers want?
  • Good practices / things to include in docs
    • Involve people who have no clue
    • Explain it to your parents
    • Friction logs
    • Guided tours / dictionary / glossary / wiki
    • Adding communications channels (how to get in touch with people)
    • How to participate and report, tailored to the project itself, through references
    • Examples
    • Use cases to show how it works without having to download packages
    • Snippets of how it works
    • Compare to other projects (links)
  • Github repositories should have
    • Description of what the project is not a fit for
    • Website
    • Doc.domain
    • Communication channels
    • Contributing.md
    • Security.md
  • Bad practices / things not to include in docs
    • Including jargon
  • Challenges to creating good docs
    • Road to simplicity is complex
    • Ordering and organizing documentation. You don’t want redundancy / duplicative docs floating around
    • Docs need to be maintained
  • How people write docs:
    • Gitbook
    • Docusaurus
    • ReadMe
      • Often more technical, and better suited for developers with context rather than beginners
    • Yay doc
    • Github wiki
  • Making life easier for contributors:
    • Bug report/fix template
    • For people that just want to learn and have fun, explaining what the project is and what they can find.
    • How to set up the environment
    • Include a sense of why things are the way they are (sometimes there are good reasons for carrying technical debt)
    • How your label system works
    • Have a roadmap that can be shared
    • Contributor License Agreements (CLAs)
    • Time expectations
      • Estimates of how long it should take to review / merge
    • Acknowledgement
      • How can you expect to be rewarded
    • Code style
    • Commit standards
    • Expectations
      • What types of contributions are in scope and out
  • How to contribute to docs for other documentarians:
    • Describe where they exist
    • Style guide
    • Linking system
    • Watch out for headings and links
    • If getting published to a website, explain the system that builds the docs
    • Cheat sheets (i.e., markdown)
    • International structure (translate)
  • What to include for sponsors:
    • Metrics
    • Donate button
    • Expense policies
    • Expectation setting
    • Success stories
      • Include what you have done with the money
    • Find a way to tell people that you’re looking for sponsors

Session outcomes and action items:

  • Every project needs good docs
  • You have different people coming to your docs. Write and consider the following:
    • Sponsors
    • Beginners
    • Designers
    • Contributors
    • Search engines
    • Other documentarians
    • International contributors
  • Build a repo with all of these good practices / personas / checklists and where it’s going to live
    • github.com/thegooddocsproject