Ask HN: How does your team keep informal documentation? | Hacker News Reader

Ask HN: How does your team keep informal documentation?

4 pointsravenstine10 comments

My engineering team has been spending the day discussing how we want to improve our practices moving forward.

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?

In my experience it's usually about finding not the most optimal tool, but the lowest common denominator: something everyone 1) has access to 2) can use with minimal fuss 3) doesn't hate. They don't have to love it, they just have to be willing to tolerate it.

Depending 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.

We use a git repository full of markdown files for out team's documentation and it works really well for us.

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)

We use a variant of git+markdown as well, but it has a problem when non technical people want to contribute to it. Some non technical testers or product people don't know a lot about git or markdown making it non trivial to contribute.

If one of our less technical colleagues need to contribute they usually use the editing options in the GitLab project - they're already used to the interfaces as we make a lot of use of their issue boards.

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.

I dont want to downplay your experience. IMHO there is enough markdown editors and visual guis that this is trivial. Even if the git repo is just commit everything to main. They might not even need to know about branches.

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.

Something extremely simple, like markdown files in the repo. The same way you dont like confluence, you might settle on x and someone might not like it later and change again. Simpler solutions lower friction.

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.

I have always wanted an internal blog where team members could independently conduct research, discuss their methodology, post their findings, and finally suggest recommendations.

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.

We theoretically use the Microsoft tools (Teams/Sharepoint/Azure DevOps) for this. The problem is that the friction of using them is so high that nobody really does -- so we have little in the way of informal documentation other than explanatory emails from other devs.

What I prefer for this, because it has always worked well in other places I've been, is just a simple locally-hosted wiki.

I was invited to a project that uses "notion.so" a couple weeks ago. It seems to work pretty well for what you're described.

Confluence is good-enough™ for us, discoverability is terrible, but search works pretty well.

We link to these documents in PRs, code-comments and slack discussions.

Reply on news.ycombinator.com