Several of the past Tech Tuesdays have been about topics that often get short shrift in startups, including security, backup and disaster recovery planning. Today I want to write about another topic in that annoying-but-needs-some-attention category: documentation.

One of my very first experiences in commercial software development had me working as a 17-year old in a small software company in my hometown in Germany. The project they dumped into my lap was to port an accounting system from an early version of Basic into a more modern dialect. The software came in 99 files with variable names of at most 2 characters in length (that had been a constraint of the variant of Basic that it was written in) and most importantly not a single line of comment or any other external documentation!

I suspect that many startups find themselves in somewhat similar situations: lots of code and very little in the ways of documentation. Often as an investor when I do tech due diligence and start to ask for an architecture diagram people get up, head over to the white board and start to draw. Very rarely does someone say instead “oh let me pull up our documentation and show you.”

As always let me start by saying that the best documented system doesn’t mean a thing if it’s not solving a problem that people actually have. So like with security, backup, etc. you want to start out with the minimum possible and focus on product market fit. That minimum though is above the extreme case that I encountered on my first job and that I still find in startups.

Fortunately we have made a lot of progress with tooling and I am a big fan of documentation that is mostly auto generated pulling together method signatures, API calls, etc and extracting comments from the code to go along with those. There should be as little documentation as possible that needs to be maintained separately and updated manually as the code changes. That always has a tendency not to happen and drift away from the actual code which may make it worse than no documentation. In the early days you can get away with keeping that on a whiteboard both for easy updating and visibility.

Maintaining a base level of documentation will make it much, much easier to onboard new team members as you grow. And having a few high level diagrams that are up-to-date will keep you everyone working towards the same big picture. All of that of course also helps when an investor (or acquirer for that matter) wants to do due diligence.

Would love to hear what folks consider the MVD - minimum viable documentation. Als what tools if any are you using for that?

Several of the past Tech Tuesdays have been about topics that often get short shrift in startups, including security, backup and disaster recovery planning. Today I want to write about another topic in that annoying-but-needs-some-attention category: documentation.

One of my very first experiences in commercial software development had me working as a 17-year old in a small software company in my hometown in Germany. The project they dumped into my lap was to port an accounting system from an early version of Basic into a more modern dialect. The software came in 99 files with variable names of at most 2 characters in length (that had been a constraint of the variant of Basic that it was written in) and most importantly not a single line of comment or any other external documentation!

I suspect that many startups find themselves in somewhat similar situations: lots of code and very little in the ways of documentation. Often as an investor when I do tech due diligence and start to ask for an architecture diagram people get up, head over to the white board and start to draw. Very rarely does someone say instead “oh let me pull up our documentation and show you.”

As always let me start by saying that the best documented system doesn’t mean a thing if it’s not solving a problem that people actually have. So like with security, backup, etc. you want to start out with the minimum possible and focus on product market fit. That minimum though is above the extreme case that I encountered on my first job and that I still find in startups.

Fortunately we have made a lot of progress with tooling and I am a big fan of documentation that is mostly auto generated pulling together method signatures, API calls, etc and extracting comments from the code to go along with those. There should be as little documentation as possible that needs to be maintained separately and updated manually as the code changes. That always has a tendency not to happen and drift away from the actual code which may make it worse than no documentation. In the early days you can get away with keeping that on a whiteboard both for easy updating and visibility.

Maintaining a base level of documentation will make it much, much easier to onboard new team members as you grow. And having a few high level diagrams that are up-to-date will keep you everyone working towards the same big picture. All of that of course also helps when an investor (or acquirer for that matter) wants to do due diligence.

Would love to hear what folks consider the MVD - minimum viable documentation. Als what tools if any are you using for that?