4 ms·

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

by spolsky 15y ago

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.

MartinCron 15y ago
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.
- gabyar 15y ago
  Rewriting the spec for a feature takes a lot less time than rewriting the code.
  - MartinCron 15y ago
    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.
kurin 15y ago
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.
- marklittlewood 15y ago
  Isn't that why Balsamiq exists?
  - JayInt 15y ago
    Wouldn't it be cool if it integrated with Trello just like it does with FogBuzz!
- MartinCron 15y ago
  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.
  - wjgilmore 15y ago
    +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. :-)
olavk 15y ago
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.
- vog 15y ago
  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.
  - drothlis 15y ago
    Have you written up your approach to / experiences with literate programming anywhere?
    - vog 15y ago
      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://en.wikipedia.org/wiki/Literate_programming - http://www.literateprogramming.com/ 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 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 http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf
StavrosK 15y ago
Sidenote: "Trello" is Greek for "crazy".
tianshuo 15y ago
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?
- MartinCron 15y ago
  Lots of people want to join Joel's fabulous team. Let us know if this approach works out for you.
badclient 15y ago
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.

by spolsky 15y ago

MartinCron 15y ago

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.

gabyar 15y ago
Rewriting the spec for a feature takes a lot less time than rewriting the code.
- MartinCron 15y ago
  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.

kurin 15y ago

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.

marklittlewood 15y ago
Isn't that why Balsamiq exists?
- JayInt 15y ago
  Wouldn't it be cool if it integrated with Trello just like it does with FogBuzz!
MartinCron 15y ago
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.
- wjgilmore 15y ago
  +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. :-)

olavk 15y ago

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.

vog 15y ago
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.
- drothlis 15y ago
  Have you written up your approach to / experiences with literate programming anywhere?
  - vog 15y ago
    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://en.wikipedia.org/wiki/Literate_programming - http://www.literateprogramming.com/ 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 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 http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf

StavrosK 15y ago

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

tianshuo 15y ago

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?

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

badclient 15y ago

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.