Our great sponsors
-
documentation-framework
"The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
I would not suggest people to follow this in 2024 if they are building any system of non-trivial scope and expect it to be adopted by others who are not required to adopt it.
Back in 2017, I compared "code as documentation" to being dropped into on the street of an unfamiliar city, while a good documentation can serve as a map of the city. [1]
Nearly all recent successful efforts for large new systems understand the value of both high-level overviews and detailed examples / onboarding materials to make adoption easier. When solutions to a certain problem are abundant, people do not need to settle for options that do not have great supporting documentation of the four primary kinds. [2]
[1] https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i...
[2] https://documentation.divio.com/
> If you learn something the hard way, share your findings with others. You have blazed a new trail; now you must mark it for your fellow travellers. Sharing knowledge is an unreasonably effective way of helping others.
This is a really nice philosophy. It's one of the reasons why I have my https://til.simonwillison.net TIL site - any time I search for something and can't find the answer is a hint that there's a tiny gap in the internet which I can help fill.