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
@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..
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.
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
@firstname.lastname@example.org I believe "code comments in unmerged branches" probably also deserves to be on this list. Also, "Medium"
@email@example.com 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 * surface of the blackholes
@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!
Lars and friends