Ask HN: How does your team keep informal documentation?
A point that I brought up was that we could benefit from keeping what I refer to as "informal documentation" that is internal to our team (not org-wide), which I imagine as being just a place to share information that could be beneficial for the rest of the team. The reason I emphasize informality is that I've rarely seen more formal documentation work well at any company I've been at. Usually what happens is documentation is gatekeeped and the platform used is crummy. If I want to write an article on something I think is important, I should just be able to do it.
For instance, if an engineer works on a project and develops some patterns or APIs they have a lot of knowledge about, they could write that information down for other developers in the future. My idea isn't to create elegantly structured documentation that should be guaranteed to be up to date, but to write notes or even record videos in an informal way, as if you're chatting with a fellow dev sitting next to you. There would be no gatekeeping; if any developer sees something they can improve or correct, they can do so without asking permission.
My fellow team members seem to like this idea. However, I don't know what platform or tool would be ideal for this.
Our company has Confluence, but I personally don't like it and most of the company doesn't like it. GitHub PR descriptions/threads somewhat fill that gap, but navigating this information can be difficult, and becomes more difficult the older a PR gets.
How does your team achieve what I'm looking for? Does your solution work well? What is a tool or platform that you've found success with that you can recommend for this purpose?
10 comments
[ 4.3 ms ] story [ 35.9 ms ] threadDepending on the team, sometimes that's just a Github Wiki attached to the repo. Or just a really long README.md with different sections. Sometimes that's a bunch of comments in the code. Sometimes that's Google Docs scattered all over the place. Sometimes, yes, it's Confluence or Notion or ClickUp or whatever some decision maker decided to buy without consulting anyone.
Just start writing. Once you get a critical mass, either people will start to adopt it, or you find that it's not really a platform problem but a cultural one, in which case probably no tool will work.
Benefits include:
* It's really simple for people to use and update.
* Everyone can keep a copy locally on their own machines in case they're stuck without access to the GitHub/GitLab instance
* People are much happier removing out of date information from it as they can always find in the history again if they need it
* Branches in documentation can be really useful when you're making big changes (or an individual wants to add personal comments to their local copy)
As a bonus most of them also pick up a basic level understanding of git, which helps them join in other conversations they didn't previously feel they could.
As for markdown, it is so trivial, especially with previews anywhere, that this is a made up problem. I think these "non-technical" people can learn this if needed, and if they have the will.
We link to these documents in PRs, code-comments and slack discussions.
I have never seen this at any employer.
The result of suggesting this is a lot of hostility at the idea from peers or lip service from management. So developers, like me, curious about how things really work just publish the same research elsewhere far away from the employer and just don’t talk about it at work.
Instead what you gat at work is a very corporate blog from senior leadership talking to themselves out loud or a wiki that few people bother with.
What I prefer for this, because it has always worked well in other places I've been, is just a simple locally-hosted wiki.
An often overlooked one too, is to encourage people to do very long commit messages. Then the comments are contextual.
The main problem with documentation, formal or informal, is to keep it synced with code. I dont think videos are a good idea because of that.