Hacker News new | comments | show | ask | jobs | submit login

Long ago I learned to love wikis. Mediawiki, Dokuwiki (easy to set up), or Confluence. Hardest part is to keep people from just throwing garbage everywhere--if that happens, people stop referring to the docs, and the system collapses.

The important thing about docs is to keep in mind the audience. This is important because it lets you estimate their mental model and omit things that are redundant: for example, if it's internal documentation for a codebase, there is little need to explicitly list out Doxygen or JSDoc style information, because they have access to the damned source code. External audiences may need certain terms clarified, or some things explained more carefully because they can't just read the source.

I'd say that the biggest thing missing in the documentation efforts I've seen fail is the lack of explanation for the overarching vision/cohesive architecture of the work. This is sometimes because there isn't a single vision, or because the person who has the vision gets distracted snarfing on details that are not helpful without a preexisting schema to hang them on when learning. So, always always always have a high-level document that describes the general engineering problem the project solves, the main business constraints on that solution, and a rough sketch of how the problem is solved.

Ideally, the loss of the codebase should be less of a setback than the loss of the doc.

I will say that, as your documentation improves, you will hate your project more and more--this is the nature of the beast as you drag yourself through the broken shards of your teams engineering.

Thanks for the insight!

Regarding documentation covering an overarching vision for the code: It is my experience that the person best-suited to write these docs -- i.e. The person who knows the codebase the best -- is always in demand at the company. This person has very little free time and I doubt they want to spent it writing docs for everyone else.

Is that something you've noticed?


The thing is, the company needs to understand that the smartest thing to do is to leave that person alone and task them on educating (here via docs, but also in other ways) the other developers (assuming the team is of sufficient size, which in my experience is the case as soon as total headcount is 3).

Hoarding expertise like that is a good way to waste company resources (because other devs function at a great disadvantage) and to bring down stress upon onself (becuase you become a bottleneck and that gets to be super stressful).

The fact of the matter is that it is anti-social and bad practice for these devs not to take a step back and write down the coherent vision of their product--and if they can't explain the vision in a handful of pages with some simple diagrams, they've probably deeply fucked up the design.

The company, management usually, needs to bite the bullet and sacrifice short-term firefighting ability for mid-to-long-term training.

If they won't do this, you should leave.

What you described is what I'm hoping to see over the next few months. I joined the company recently, so there's still a lot of internals that I don't fully understand.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact