Bad places for project documentation:

* blog posts
* mailing list archives, public
* mailing list archives, private
* private emails
* chat logs
* commit messages
* closed tickets
* open tickets
* letters to the editor, published
* letters to the editor, unpublished
* people's heads
* cave paintings
* DNA of custom bacteria
* interstellar probes
* value of pi

Good places for project documentation:

* project web site
* project source tree in README
* anywhere referred to explicitly from the above

Show thread

@liw So I can have a link to my documentation in the value of pi in my README and it is okay?

@liw Exception: having a site or README that only says "join our Discord" is not okay.

what's wrong with good ol' `git blame` and reading commit messages linking to original tickets?

sure it's not top-down, and you need top down as you suggested, but i wouldn't downplay bottom-up approach..

@maricn @liw It's 2am and the system is failing. I don't want to be digging through git commits and old tickets... I want clear documentation that tells me how things work.

@CarlCravens @maricn @liw Also: If I have to go to a sticky forum post I will not come out of that experience happy and ready to keep using your software unless it's absolutely necessary.

(Looking at you, Tomato firmware).

@CarlCravens @maricn @liw
If it's 2 am and the system is failing it's too late to find out how things work.

If you haven't read most of the documentation before, you won't be able to quickly find the thing you need in a top-down documentation. You're better off letting the thing burn, going to sleep, and trying to fix it in the morning.

@CarlCravens @maricn @liw
OTOH, if you have a stacktrace or an error message you can quickly:

a) duckduckgo the error message, find an old ticket, find a solution/workaround

b) find the place in the source code where it's failing, and either

b1) git blame, commit message points you to a ticket, goto (a)

b2) the code plus the comments around it let you understand how the relevant part of this software works, you add a hacky if on prod, it seems to work, you go to sleep

@wolf480pl @maricn @liw Tell that to my boss and the customers who pay me to fix it at 2am.

@CarlCravens @maricn @liw
don't deploy software you don't understand if you're expected to fix it at 2am I believe "code comments in unmerged branches" probably also deserves to be on this list. Also, "Medium" don't worry, my supervisor made a vid of me walking everybody through the code.

now that's documentation!

@liw * cosmic background radiation of basement universe.

To be fair, i'd probably write "This tipler oracle was not intended for sentient life, sorry for the inconvenience. But hey, at least you know you don't live in a simulation! At least.. unless i am too! I promise, it's not a practical joke." in there. I mean, they wouldn't be able to read the README..

@liw I don't see anything wrong with the value of pi. 🤔
At least, you know your documentation is in there.
... ...

@liw phew, glad to hear that my digits of e documentation system is still ok

@liw All the best docs I have ever written are encoded in Pi.

Even the stuff I haven't published yet.. is already there.

The intellectual property theft is killing me!

Sign in to participate in the conversation

Lars and friends