About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

In the language as it exists clearness is not so easily won. Even under the most favorable conditions, it is exceedingly difficult to attain.

— Adams Sherman Hill



Navigation





<September 2014>
SMTWTFS
31123456
78910111213
14151617181920
21222324252627
2829301234
567891011

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 7/23/2014

Totals
Posts - 2304
Comments - 2495
Hits - 1,658,997

Averages
Entries/day - 0.56
Comments/entry - 1.08
Hits/day - 406

Updated every 30 minutes. Last: 11:33 AM Pacific


  04:08 PM

I've always been leery of the/a methodology that requires a completed design before any work gets underway. In my world this has often consisted of outlines, or at the collection level, tables of contents (TOCs). The methodology seems premised to me on a kind of paradox: you design something effectively before you know what you're doing. I'm not saying that having an overall view of what you're after is bad -- on the contrary, it's hard to proceed without such a plan -- but the design-before-implementation methodology breaks down for me at the detail level. We need to write topics about a new feature; what will those topics be? Perhaps other people can see more clearly than I can, but in my view, how can you know what topics you need before you've started? What I can tell you is that I will know definitively what topics we need when I've written them.

And so for software. I am incited to make this observation by a blog post made by "max", which includes the following:
[O]ur process requires that a design document be written before coding starts. True, in my experience nothing focuses a discussion more than a document explaining the proposed course of action (possibly including discarded alternatives). So writing a design document up front is the ideal way to go: we can all discuss the proposed design, tweak it until it satisfies us, and then code. However that's not very realistic except for the most trivial designs.

I for one can't work that way (and I've tried). English simply isn't structured enough like a programming language that I can think my design in English. To design I must conjure up classes, think of their interactions, mock up a client, extract commonality, etc. The best way for me to do this is to use Java directly. Obviously, I don't need to code everything but just stubs won't do either. I discover the design as much as I think it. Indeed, in the middle of this "designing", I often realize something that will alter it significantly: a library that doesn't work as intended, an unknown limitation, a brilliant simplification… I'm glad then I didn't write the document up front, because that would require a whole new round of documentation and discussing.

So, in a way, I apply the "up front" strategy one step further: I ensure my design will hold the water before writing a whole 30 pages document with figures describing it. Anyone who has had to change a design document after the fact knows the tediousness of changing figures and text everywhere to accommodate, say, a simple change in the inheritance hierarchy. In that respect, code is more succinct to describe such relationships than a document, so it makes sense to write some code first.

[categories]   ,

|