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.
Do it or document it?
1–10 of 18 posts
Re: Do it or document it?
#2Having 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.
Re: Do it or document it?
#3Napkins. 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. ;)
Re: Do it or document it?
#4Having 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.
Re: Do it or document it?
#5Napkins. 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 invi…
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.
Re: Do it or document it?
#6Come 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.
Re: Do it or document it?
#7I like mindmaps to sketch my ideas. Its stops me from making the document formal, and keeps the ideas freely flowing.
Re: Do it or document it?
#8Having 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.
Re: Do it or document it?
#9I'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.
Re: Do it or document it?
#10Napkins. 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 invi…
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.