---
# System prepended metadata

title: How to write really good docs (with Dan Jutan) — Learn With Jason

---

# 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/)