feat: post on writing good docs

[chrisvaillancourt]

What makes good dev docs? Relate it to the purpose.

Example: PostgreSQL docs on FULL OUTER JOIN

"First, an inner join is performed. Then, for each row in T1 that does not satisfy the join condition with any row in T2, a joined row is added with null values in columns of T2. Also, for each row of T2 that does not satisfy the join condition with any row in T1, a joined row with null values in the columns of T1 is added." source.

Or more simply: "Returns all rows from both tables. If there's no match in one table, it returns NULL values for the columns of that table."

It's fine to have both, but it's more helpful to new people if you start with the simple explanation and provide nuance afterwards.

A simple example goes a long way too.

[chrisvaillancourt]

Similar blog posts:

https://emnudge.dev/blog/write-better/

https://www.mux.com/blog/the-building-blocks-of-great-docs

https://passo.uno/seven-action-model/