# How to write really good docs (with Dan Jutan) — Learn With Jason
Summary of what I learnt from the twitch stream of [@jutanium](https://twitter.com/jutanium) and [@jlengstorf](https://twitter.com/jlengstorf)
-- by [@HarshAgar29](https://twitter.com/HarshAgar29)

## Introduction

- Docs should be treated as a Product. It is their own product and it is for everyone
- Write like a product manager and not like a content writer
- Don't describe something, teach it.
- Maintenance is much more difficult than writing. You need to keep on rewriting it
- Docs are supposed to be official bible thus devs should be able to trust it no matter when they were written.

Everyone learns differently as they create a different mental model while learning. Some learn through visual models while some learn analytically. So learning things from a different perspective will be a great thing for people.

## Real World Example:

GitHub Repo: [learnwithjason.dev](https://github.com/learnwithjason/learnwithjason.dev)
[Do contribute to the project]

- Who are going to be the users of this docs.
-- Hobbyists
-- People on the team who use the project

- APIs fit with existing paradigm so it is easy to create docs for

- Learning more about docs: https://diataxis.fr/
-- Tutorials:
--- Learning Oriented. Teaching concepts
-- How to Guides:
--- Step by step guides but more specific based on user
-- Explanation:
--- Understanding Oriented page
-- Reference:
--- Information Oriented. Need to document everything but surface level

- As an alpha product, it is better to go for Tutorials and Reference because it needs to grow community with Tutorial and References are heavily needed which can also be automated a lot.
- Go for a README.md instead of a docs site for small projects. For Monorepo with lots of READMEs, put READMEs to the sub folders and link it with the main repo. It will act as a docs site.
- Have a toolkit to write docs (Eg: Hackmd)

## Work done in the Docs

- Moved the API docs to a different README.md and linked it with the root README.md
- Pointed out what the API can do as a product for the users in bullet points. Created an outline before the details.
(solidjs/solid-routers) -> It introduced the concept of routers before going for Getting Started and kept references at the end.

- Talked about the importance of Types and where it should be kept in the docs. Using automated tools is recommended here to create automated docs from types.
-- Design question: Should the user know TS as a pre-requisite or should anyone be able to use this API.

- Docs are here to help everyone but the docs creator can deviate from it based on the API design.
- Create more and different APIs in open source so that more apps can be built
-- Personal Take: Will definitely try making a Podcast API

- Learn from people doing their job with apprenticeship model. Following people on twitter who are doing work in the real world will teach a lot more than some teacher.

## References

- [People to follow Tweet](https://twitter.com/jutanium/status/1645052043655016448)
- [Rachel Nabors on Changelog](https://changelog.com/person/rachelnabors)
- Resource to learn about writing Docs: [diataxis](https://diataxis.fr/)
- Toolkit for working on markdown: [Hackmd](https://hackmd.io/)