

Do it or document it? - bh

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.
======
mechanical_fish
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. ;)

~~~
ajross
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.

~~~
eru
Wikis work good, too.

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

~~~
bmj
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.

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

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

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

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

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

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

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

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

