6 ms·

> I went full waterfall on it, the spec is 266 pages long and took half a year just to write. Why would you write a ~9k “loc” long spec over 6 month instead of

by stymaar 10y ago

> I went full waterfall on it, the spec is 266 pages long and took half a year just to write. Why would you write a ~9k “loc” long spec over 6 month instead of coding it directly ? The only reason I can think of, is if you want to out-source the development. Is there any good reason to work this way on a one-man project ?

roel_v 10y ago
Not OP, but once you have a spec, it's much easier to code up. If you're designing while you're coding, you have to switch all the time between 'how should this work' and 'how do I build this'. Thinking and writing down how something should work, should always be the first step - regardless of whether you're on your own or in a big team. (before the obvious objection: exceptions are toy programs which you write to find out how to build something, in which you focus on the technical aspects. The technical aspects ('how does it work') don't matter for the end user (= your potential customer), they only care about 'what does it do'.)
- kuerbel 10y ago
  It was a hard lesson to learn, but "Weeks of programming can save you hours of planning" holds true in almost all cases.
  - kogepathic 10y ago
    In my experience there is far too little respect for well written specifications. Most colleagues of mine and a few managers see them as a waste of time ("you're over thinking this", or "we'll figure it out later") yet somehow the projects with a specification always end up being done more or less on schedule. The thing about specifications is that you need to be open to changing them if you find it's not working out. Specifications are not synonymous with waterfall development, and it's harmful to treat and view them as such.
  - stymaar 10y ago
    I totally agree with this statement, but here we're talking about 0.5 year of planning ! Planning is important, and cautiously thinking about your features before diving in can save you weeks later on. But spending 6 month in a tunnel, writing specs you'll spend at least a year to implement, is a huge risk : what if your users only use 30% of the features you designed, and lack a missing feature you didn't plan ? You could have figured it out way sooner have you built something earlier and released it. Also, your time to market is way slower and you don't risk losing years of work by missing a deadline … > Damn, now I need to move faster. My app must be ready by the time they close Wunderlist. I expected an eventual closure, but not that soon.
    - corobo 10y ago
      > what if your users only use 30% of the features you designed Or worse, what if different segments of users only use 30% of different feature sets? See also: Evernote's 5% problem [1] [1] https://venturebeat.com/2016/01/05/evernotes-5-problem-offers-a-cautionary-lesson-to-tech-companies/ https://venturebeat.com/2016/01/05/evernotes-5-problem-offer...
    - obsurveyor 10y ago
      > I totally agree with this statement, but here we're talking about 0.5 year of planning ! Yeah but that's not necessarily in man-years. Maybe he worked on it an hour or two a day. Now we're talking around two man-weeks of planning.
    - roel_v 10y ago
      Well you'll only find out which 30% after building it, regardless of whether you have a spec or not. You can write a.spec for an mvp too.
- psyc 10y ago
  I never plan. I just code. I end up writing 10 versions of every module, and retrofitting everything that touches it 10 times as well. What I'm trying to say is that I think... I think you might be on to something :)
_jal 10y ago
> Is there any good reason to work this way on a one-man project ? (Not the OP.) At least for me, emphatically yes. From your question, it sounds like you're only considering the communicative value of a spec. That's of course important, but I consider it secondary. Writing a good spec forces you to think through what you're developing in an orthogonal way. You're thinking through flow, cohesiveness, design, some implementation, UI, etc. together at a high level. I love having the time to write a spec when I'm building something nontrivial. I've found numerous problems that I wouldn't have otherwise by doing so, ranging from simple UI problems/contradictions to spotting unconsidered assumptions that would have lead me down dead ends. A spec and the application should naturally co-evolve during development to some extent. But the spec also provides an anchor for what you're doing, as well as a map. It is very, very helpful if you Do It Right(tm), no matter the size of your team.
- VladimirGolovin 10y ago
  Writing a good spec forces you to think through what you're developing in an orthogonal way. (OP here). This. A thousand times this.
  - trashabout 10y ago
    Did you follow any standards when writing? I am currently looking for ways to document and model our process and business rules.
    - VladimirGolovin 10y ago
      I just wrote well-structured, dense, coherent / "mentally type-checked", bulleted-list prose, often copied directly from Workflowy. Some of the critical parts were described with FP-style pseudocode, for greater exactness.
      - trashabout 10y ago
        thanks!
VladimirGolovin 10y ago
(OP here) This is not a one-man project. I'm the founder, and there's a UI designer and two coders - which makes it 4 people total. And we'll add another dedicated coder for iOS development, when we find a good one.
aquadrop 10y ago
It's so you won't have multiple 'ooh' moments a year in coding - "I need to change that base thing, will require large rewrite". Or at least decrease possibility of it. Six months seems a bit too long even for 266 pages specs though.

by stymaar 10y ago

roel_v 10y ago

Not OP, but once you have a spec, it's much easier to code up. If you're designing while you're coding, you have to switch all the time between 'how should this work' and 'how do I build this'. Thinking and writing down how something should work, should always be the first step - regardless of whether you're on your own or in a big team. (before the obvious objection: exceptions are toy programs which you write to find out how to build something, in which you focus on the technical aspects. The technical aspects ('how does it work') don't matter for the end user (= your potential customer), they only care about 'what does it do'.)

kuerbel 10y ago
It was a hard lesson to learn, but "Weeks of programming can save you hours of planning" holds true in almost all cases.
- kogepathic 10y ago
  In my experience there is far too little respect for well written specifications. Most colleagues of mine and a few managers see them as a waste of time ("you're over thinking this", or "we'll figure it out later") yet somehow the projects with a specification always end up being done more or less on schedule. The thing about specifications is that you need to be open to changing them if you find it's not working out. Specifications are not synonymous with waterfall development, and it's harmful to treat and view them as such.
- stymaar 10y ago
  I totally agree with this statement, but here we're talking about 0.5 year of planning ! Planning is important, and cautiously thinking about your features before diving in can save you weeks later on. But spending 6 month in a tunnel, writing specs you'll spend at least a year to implement, is a huge risk : what if your users only use 30% of the features you designed, and lack a missing feature you didn't plan ? You could have figured it out way sooner have you built something earlier and released it. Also, your time to market is way slower and you don't risk losing years of work by missing a deadline … > Damn, now I need to move faster. My app must be ready by the time they close Wunderlist. I expected an eventual closure, but not that soon.
  - corobo 10y ago
    > what if your users only use 30% of the features you designed Or worse, what if different segments of users only use 30% of different feature sets? See also: Evernote's 5% problem [1] [1] https://venturebeat.com/2016/01/05/evernotes-5-problem-offers-a-cautionary-lesson-to-tech-companies/ https://venturebeat.com/2016/01/05/evernotes-5-problem-offer...
  - obsurveyor 10y ago
    > I totally agree with this statement, but here we're talking about 0.5 year of planning ! Yeah but that's not necessarily in man-years. Maybe he worked on it an hour or two a day. Now we're talking around two man-weeks of planning.
  - roel_v 10y ago
    Well you'll only find out which 30% after building it, regardless of whether you have a spec or not. You can write a.spec for an mvp too.
psyc 10y ago
I never plan. I just code. I end up writing 10 versions of every module, and retrofitting everything that touches it 10 times as well. What I'm trying to say is that I think... I think you might be on to something :)

_jal 10y ago

> Is there any good reason to work this way on a one-man project ? (Not the OP.) At least for me, emphatically yes. From your question, it sounds like you're only considering the communicative value of a spec. That's of course important, but I consider it secondary. Writing a good spec forces you to think through what you're developing in an orthogonal way. You're thinking through flow, cohesiveness, design, some implementation, UI, etc. together at a high level. I love having the time to write a spec when I'm building something nontrivial. I've found numerous problems that I wouldn't have otherwise by doing so, ranging from simple UI problems/contradictions to spotting unconsidered assumptions that would have lead me down dead ends. A spec and the application should naturally co-evolve during development to some extent. But the spec also provides an anchor for what you're doing, as well as a map. It is very, very helpful if you Do It Right(tm), no matter the size of your team.

VladimirGolovin 10y ago
Writing a good spec forces you to think through what you're developing in an orthogonal way. (OP here). This. A thousand times this.
- trashabout 10y ago
  Did you follow any standards when writing? I am currently looking for ways to document and model our process and business rules.
  - VladimirGolovin 10y ago
    I just wrote well-structured, dense, coherent / "mentally type-checked", bulleted-list prose, often copied directly from Workflowy. Some of the critical parts were described with FP-style pseudocode, for greater exactness.
    - trashabout 10y ago
      thanks!

VladimirGolovin 10y ago

(OP here) This is not a one-man project. I'm the founder, and there's a UI designer and two coders - which makes it 4 people total. And we'll add another dedicated coder for iOS development, when we find a good one.

aquadrop 10y ago

It's so you won't have multiple 'ooh' moments a year in coding - "I need to change that base thing, will require large rewrite". Or at least decrease possibility of it. Six months seems a bit too long even for 266 pages specs though.