loading words...

Jan 13, 2019 22:27:38

README is not docs

by @swizecteller | 222 words | 🐣 | 116πŸ’Œ

Swizec Teller

Current day streak: 0🐣
Total posts: 116πŸ’Œ
Total words: 32303 (129 pages πŸ“„)

Today I learned that README.md is not documentation #200wordsTIL


Since GitHub, most source projects have some basic documentation in README.md. Great innovation, improved open source software 100x.

Remember the old days when your best bet for current documentation was hunting for recent blogs from people clearing the minefield before you?


README.md changed everything.

You can find basic docs on every repository. Right where you find the code. The first page you see is a basic description of what this library does, how to use it, and some examples of what to expect.

It's great πŸ‘Œ


It works so well because the docsare part of the code repo. No more do maintainers have to do [too much] extra work to keep docs up to date.

All your fav PR and code tools work for docs. Wunderbar!


So Swiz why are you complaining? This is awesome!

It is.

Except when the docs are TOO up to date.


README tracks the master branch, but the master branch doesn't track the current best version. It tracks the 𝘧𝘢𝘡𝘢𝘳𝘦 version.

And you don't know it's a breaking update. You're just confused why following the docs breaks your code.


I don't have a solution ... "Be mindful and provide stable docs outside the readme" maybe?

But then you're back to all the same problems we've always had. 

Docs are hard. πŸ˜•

Originally published at twitter.com

contact: email - twitter / Terms / Privacy