Docs as code at Forma.ai¶

Benefits of docs as code¶

We were using Bookstack

Most of our devs work on the backend.

They may not know React

We also don't need a single page app.

[ ] integrate into codebase and engineering workflow
- [ ] for engineering docs
[ ] Decrease the fragmentation of the docs
[ ] Get feedback from users about the docs
- [ ] drift: how in sync are the docs with the code
- [ ] did you find what you were looking for?
- [ ] 👍 or 👎
- [ ] how many views does each page get?
[ ] User documentation
- [ ] Commissions Analysts
- [ ] Sales Reps
- [ ] Financial Business partners
- [ ] HelpJuice?
[ ] Find an alternative to diagrams.net to create diagrams
- [ ] inside the markdown?
- [ ] excalidraw
- [ ] mermaid
- [ ] diagrams
- [ ]

Documentation quality audit

Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:

g3docs
enable engineers to find, create and maintain docs
- keep docs in a simple, portable format (Markdown)
- next to its associated code
- rendering it at a logical URL
Why people don't like docs
- they don't exist
- they're hard to find
- they're wrong
Why don't people write docs
- no time
- no incentive
- no culture

more layers of separation/time between implementation and writing the docs
- more inaccurate docs
devs dislike the workflow of writing docs
- have to switch tools
- gets pushed off
treat docs like code
- docs are stored in git
- build doc artifacts (website) automatically
- trusted set of reviewers to review docs
- docs are tested
  - content accurate?
  - do the links work
what we gain
- promotes collaboration
- tracks doc mistakes as bugs
- include docs in code review
- beautiful, uniform docs
versioning docs
types of docs
- long form docs
  - user guides
  - getting started, FAQs
- Functional docs
  - REST APIs
  - SDKs
  - man pages
mkdocs

docs are communication
why do people read docs
- great docs serve multiple conflicting users
  - need to document things multiple times
- new users
- education
- support
- troubleshooting (annoyed users)
- learning internals (devs)
- reference
who should write docs
- great developers (the person who wrote the feature)
  - Django requires that new patches come with new docs
  - the person who just wrote the code knows about it the most
  - write something and get feedback
  - wiki is where good docs go to die
  - wiki tells me that you don't really care about your docs
what should we document?
- Tutorials
  - quick (new user should feel a win within 30 mins)
  - easy but not too easy
  - show off how the project feels
- Topic Guides
  - Conceptual
    - tutorials are about parroting
    - topic guides: kick them out of the nest
  - Comprehensive
    - tell the WHY of the topic
- Reference
  - complete
  - for experienced users
  - HOW of the topic
  - Igor doesn't like auto-generated reference
- Troubleshooting
  - answers to questions asked in anger
  - FAQ need to be frequently asked
which tools should we use?
- tools don't matter (but use good ones)
- Sphinx
- Docco and Pycco