Hacker News Reader

Comment by spolsky | Hacker News Reader

It's more complicated than that, and it's hard to answer here.

Basically -- if you're building something big and complicated and you should know exactly how it's going to work, a big written spec really helps.

If you're building something brand new, a startup, or a crazy idea that you need to test quickly and iterate, you should use lots of little specs. It's ok if the specs aren't so fancy... a detailed map of what goes on the screen and what everything does is probably fine. It's ideal if you write lots of small specs for each small feature ("user story") right before you implement them and roll them out.

I just don't like the idea of typing code when you haven't thought through what it's supposed to do (in a disciplined way). Doing specs in small quick chunks, then writing code, is probably the best approach for lean/agile startup teams that don't yet have customer/product fit.

View on HN

Thanks for the response. I see where you're going from. I only brought it up because my development organization would fail that part of the Joel Test, where many totally dysfunctional organizations I have worked with would pass. Doesn't pass my initial smell test.

It's easy to see someone jumping in and writing and re-writing code when they haven't thought it through as wasteful. People have a harder time seeing that writing and re-writing specs can be similarly wasteful.

Rewriting the spec for a feature takes a lot less time than rewriting the code.

And reworking a whiteboard sketch for a feature takes a lot less time than rewriting the spec.

I think Joel's comment of "thinking in a disciplined way before typing code" hits the nail on the head. Different people can think in disciplined ways before typing code. Some people do that by writing specs, other people do that by writing tests, others do it at the whiteboard. There's no one right way to do it.

As someone who can't draw a thing, there's a phenomenon I've noticed that might apply. Every time I need to draw something out, I try to hold it clearly in my head, where it looks so complete, but of course it never works. My suspicion is that instead of actually seeing the details of what I want to draw in my head, my brain has filled them in with "here be details," which makes for a nice mental image but that doesn't really play so well on paper.

I also think the same thing happens when we write software with loose mental maps. Our brains fill in the gaps with "yadda yadda yadda," to make it feel complete, but really there's nothing there at all.

Isn't that why Balsamiq exists?

Wouldn't it be cool if it integrated with Trello just like it does with FogBuzz!

As someone who can't draw a thing

Practical suggestion that has worked for me is to use graph paper. Having the grid to align and separate things makes a huge difference. My non-graph-paper sketches look like something from a lunatic's diary in comparison.

I would be eager to try a whiteboard with a consistent faint grid to it.

+1. I can't draw a smiley face. Plain old graph paper has had a huge impact on my ability to put together satisfactory mockups. I have a pile of it sitting right next to me in fact. :-)

I would really like a tool that would allow a spec and development notes to evolve just as a program evolves. It should start out with being as simple and low-overhead to use as a few post-it notes, but as the projects gets bigger it should be possible to impose structure, like categorize notes into functional spec or requirement, user stories etc, prioritize etc.

I believe this is called literate programming (LP), which focuses on real documentation (in the broader sense, including specs, etc) rather than mere API docs. There are quite a lot of LP tools, many of them being independent from the language.

However, LP is not about tools. I've written LP programs that don't need any extra tool[1]. Rather, LP is about putting the documentation (spec, requirements, etc) at the highest level, and make the code a sublevel of that. This is very different from the traditional approaches where code is the highest level, or where documentation and code are separate.

[1] This worked because the build script was part of the literate program, too. Many "problems" with LP solve themselves if you just apply LP consequently.

Have you written up your approach to / experiences with literate programming anywhere?

I'm not an expert on that topic, others have written it up better than I could:

- http://en.wikipedia.org/wiki/Literate_programming

- http://www.literateprogramming.com/

Nevertheless, I have done some experiments. Some time ago I submitted a small demonstration about "Self-Contained Literate Programming" to HN. It seems to have vanished, so I just resubmitted it. It would be great to get some feedback/discussion about that:

- http://news.ycombinator.com/item?id=2995845

Together with some other students, I also created some homework for university in LP style (sorry, in German language only):

- http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf

That is interesting, and perhaps part of what I am looking for.

But I'm not sure that things like feature proposals, high-level requirements and architecture overviews fits into a literate programming model.

Why not? For instance, feature proposals are just the previous phase of high-level requirements. And high-level requirements are just the previous phase of (or introduction into) the spec.

I'd think of it as a big documentation where some parts are complete and mature (down to the level of code), while other parts are still in draft (feature proposals).

Or change management: Of course everything should be under version control. And I guess that bug descriptions should still be part of a ticket system or at least the commit messages. But I never understood why feature proposals are discussed more in a discussion-based manner (ticket system) rather than a document-based manner (wiki, or documentation).

Unfortunately, I was never part of a development team which was seriously into LP, so my suggestions are only based on my understanding of LP, and small proof-of-concepts on my own.

I'd love to read about bigger real-world projects which apply LP, or which at least apply some other documentation-driven approach.

Sidenote: "Trello" is Greek for "crazy".

This actually sounds more like lean startup than unlike it. Yes lean startup encourages getting to testing your ideas quickly, but it also focuses on reducing process waste. If you have a mature product and enough data points suggesting major new feature, I think it'd be a waste to try and recollect those data points or build half of the features just for the sake of being lean even if in the past you have been mostly spot on with taking customer feedback and releasing successful major features based on them.

Hey Joel, this is terrific, and what's on my mind for quite a long time. None of the present kanban implementations are good, and I've been thinking of using node+socket+backbone to build one in my spare time. I've also downloaded the iPhone version but it lacks a lot of polish. TL;DR I like trello, and could I join your fabulous team?

Lots of people want to join Joel's fabulous team. Let us know if this approach works out for you.

Reply on news.ycombinator.com