Do it or document it? | Hacker News Reader

Do it or document it?

21 pointsbh15 comments

I come from a corporate IT background that involves lots of formal up-front documentation. I now have a startup project I want to work on, and my head is telling me to start writing documents, preparing detailed designs, etc. But my heart just wants to get in there and build the thing. I wondered how many 'successful' services knocking around today didn't start out with a written design - I'm thinking along the lines of Twitter, Wesabe, etc.

View on HN

Napkins. The solution you're looking for is napkins. But, it's true, they're hard to write on, so we'll compromise.

Take a pad of paper and a good pen (hint: Pilot G2) and go to a place that is entirely free of computers. Coffee is optional.

Start sketching. Your goal is a set of notes, an outline, a diagram or two, and/or some paper-based UI wireframes that describe your project. Imagine that you're trying to invite a recent comp sci grad to work on your project with you: What might you sketch? Draw that.

You can use emacs if you want, but on no account should you allow yourself to choose a font for your spec. If you find yourself reaching for the Fonts menu, or wondering whether your spec should have a standardized header and footer, you have stopped planning and started procrastinating.

You need to do some planning, because you don't want to waste time implementing stuff that doesn't even work on paper. But you don't necessarily need a capital-D Document, or even a real presentation. Once the napkin sketch of your finished product is complete, to your own satisfaction, it's time to build the prototype and observe all your mistakes. ;)

Yeah, indeed. The word to eject from the process is "formal", not "documentation". Write stuff down however it works for you: be it email, IRC logs, napkins, whiteboards, whatever. Refine as needed. Write summaries every few ideas.

If the problem is of the right size, bang out prototype scripts and let these serve as "documentation" too.

But scrap the endless cycles of proposals, reviews, designs and revisions. Do that stuff implicitly.

Yes I think this hammers an important point. Write with what helps you think, For me It has to be an uber size blank sheet of paper and I just start planning. After the paper I can usually go to a laptop an either make a rough prototype or at least a structure in code. I don't know why I can't seem to code directly.

To repeat do what helps you think faster/clearer/better

Wikis work good, too.

Agreed.

Until your company is fairly large (maybe 20 people?) document for yourself. It's your business, so you can do whatever you want, but I'd suggest writing things down that will help _you_ in three months when you have to look over something you did before.

With that in mind you should decide what you value. The small company teams I've worked on have exchanged virtually all knowledge verbally, and we would only ever draw whiteboard diagrams of things for new hires, which was convenient because the stuff seems to change as fast as the ink dries.

Having done both, I'd say:

1. In a startup you do it*

2. In a big company you document it

* that's not to say you don't do some planning and sketching and the like, but you don't need a ginormous stack of docs.

It's worth remembering that one significant reason for heavy documentation is accuracy/fidelity of ideas when transmitting/coordinating across a large team of people.

I agree, but there can be some danger in this as the start-up grows. I worked for a "we'll figure it out as we go along" start-up, but as clients grew (and the original dev left) the rest of us were left with nothing more than generally uncommented code as documentation.

Come up with a loose guideline. If your spec is more than a page, and rigidly specifies stuff, you've over specified. The idea is to get an idea of how the system fits together and what the components are needed for putting it together, not to detail exactly how each part behaves.

Then, as you implement, fill in the blanks in your initial spec. Make sure that if it's implemented, it's fully documented.

Having too much formal documentation and specs will box you in. Having a more unencumbered plan of development can potentially point you to where your plan was lacking to begin with and tweak your idea in the process.

But if you have a lot of experience with very well-defined, planned projects, by all means try to make the best of it.

Depends on your expected rate of growth, and how much time you expect each developer to waste in bootstrapping and mentoring. When you consider getting your third developer, then is the time to start thinking about documentation processes (as in managed and computer-accessible, not Z or UML).

Having been the second in a few startups, I can tell you that not having any sort of documentation is annoying. Do not expect anyone to read your code and understand how your mind works: if you don't document, you will have to sacrifice a significant amount of time training the new employee. You'll have to hire during a lull, and in a startup there's never a lull. As usual, Fred Brooks said it first.

Finally, Twitter is a good example of what acting first then designing second can achieve: unfixable scaling issues. Don't do that.

Is Z still used? I once read a book about it - but that was some time ago.

I'm in a similar situation. I think ultimately show don't tell is the most important adage. I introduced a wiki (mediawiki) where I work and it's been great. At some point when things grow you have to start communicating things and the wiki doc is the right level IMHO and not too labour intensive. Also a good scratchpad that can evolve documentation as it's needed. Internal private discussion boards I find are also good because often a good record of informal chats about problems to which everyone can chime in. Also scenario oriented design is what I find works, means the actual problem is well understood and communicated rather than a DUF approach which can kill iterative innovation and prototyping I've found.

You will have to look at documentation like everything else having to do with your startup. Document only if it provides a high return on your time and resources. Ask yourself at each point while you work on your project: 'What can I do now that benefits my business the most?' When the answer is documentation, then document. That's a major benefit of running your own business: no one gets to dictate your priorities to you. So enjoy that freedom.

I like mindmaps to sketch my ideas. Its stops me from making the document formal, and keeps the ideas freely flowing.

Thanks for your comments everyone. Some valuable input there, as usual. :)

Reply on news.ycombinator.com