wood burning stoves*
The moose likes Agile and Other Processes and the fly likes Technical Specs, anyone? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Technical Specs, anyone?" Watch "Technical Specs, anyone?" New topic
Author

Technical Specs, anyone?

Elle Atechsy
Ranch Hand

Joined: Jan 23, 2004
Posts: 96
Hi All,

For most of my web app projects, I did not write tech specs, only functional design specs. I regretted not writing tech specs, because one time I ended up in the hospital for an appendectomy, and was therefore out of work for a week. I had spoken to everyone regarding their assignments, they took notes. Though, not thoroughly, so most were always at my desk with questions when I was there. Also, I believe some were starting new assignments that weren't explained yet. So, during that week everyone was completely lost. Not only that, but standard app framework was hard to manage bacause everyone did what they wanted to do.

This time around, with a few more experienced java developers, and 6 more coming next week, I tried breaking the project up in modules, and assigning leads to each module. Each of them, and myself are to write technical specs for our modules. That way the new developers that are coming can read/code, read/code, read/code, ask a few questions, then read/code, read/code, read/code again.

The problems are:

1: Most of the leads claim that they can write the code faster than to give so much detail in a tech spec.

2: Most, including myself, don't know what the format of the document should be, as I've never seen one until a template found by one teammate.

3: Although this template was used, we have tech specs for each module that looks very very different than one another because everyone wants to re-format to their understanding & only include certain information, that is, in my opinion, not enough.

Does anybody write tech specs?

If not, how do you control the confusion?

If yes, can anyone suggest a template that has worked well for them?


Thanks in advance!
Lulu
[ February 27, 2007: Message edited by: Lulu Carr ]
Mark Herschberg
Sheriff

Joined: Dec 04, 2000
Posts: 6037
Great questions, but probably ones more appropriate for the process forum.

--Mark
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
The Agile Practitioners here will tell you in an ideal world you would eliminate that stratification on the team where some people can be trusted to design and others can't. You get there via face to face communication in a small, colocated team, pair programming. The need for documents largely goes away when everybody understands the architecture, its goals, values, principles and styles.

But I'm plenty familiar with the kind of teams you describe, especially where a number of "augmenters" may float on and off the project. I've written framework cookbooks that I was very proud of and found that nobody read them, so I know there's no simple answer about what you should write up.

Start here:

_______ needs to learn _______ so they can ________

Is a document the best way to communicate? The answer is rarely yes, because conversations, interactive discussions, recordings, etc. communicate so much better. But sometimes a document is the only choice. So now fill in

_______ reads ________ to learn ________ so they can ________

Focus on one document that tells one person what they need. You have to know the reader pretty well to give them exactly the right content. Documents that try to tell everybody everything never work. I wouldn't spend a lot of time looking for the magic template that will make this job easy.

Any of that help?
[ February 28, 2007: Message edited by: Stan James ]

A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Elle Atechsy
Ranch Hand

Joined: Jan 23, 2004
Posts: 96
Hi Stan,

Yes, your comments help very much. I would like to confirm that your fill-in phrases mean document only what the developers need to know so they can execute the appropriate steps to construct the app. The 2nd phrase, however, is tailored more to an individual.

If I understand correctly, because I have not read much on the Agile deveopment process yet:

Does developers design/write specs/develop each module as you go along with the project, and tailor each tech spec to the developer(s) who will construct those tasks?

Also, should everyone be involved in the inital design so that they understand the overall architecture, goals, etc? Or, is it that since, each piece is being designed as you go along, only the persons who will construct it needs to be involved in the design phase of that section of the project?

One more, using this process, how does it help adding new developers being added to the group in mid development cycle?

Thanks!
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Agile folks would avoid a designer handing off a design to an implementer. Instead they might take every task from beginning to end with a developer (or pair), a customer (business / requirements expert) and a tester (if they have any.) Together they work out what is needed and how they know when it's done (the tests). Since they work all this out together, there's no need to write anything down to hand from one person to the next.

There may be a need to write things down for external partners, managers or future generations, but be skeptical about those needs. That's where the fill-ins come in. If you can't make a compelling statement about who will read it and why, don't write it down.

Agile teams would also operate in a common room. For software design a developer might grab one or two others and work something out on a whiteboard. If it seems important, they might leave it there and talk about it with everybody else, or even take a photograph. Since everybody is exposed to so so many parts of the design, they can develop a common vision and architecture direction together. You don't have to worry much about a rogue developer doing something outside the conventions.

It sounds like you have tiers of designers and developers, maybe because of skill gaps or politics or whatever. If you can't eliminate those, you probably can't get to all the other agile goodness. I like the Agile values but I can't tell you that they are the answer to your problems because you may not have an environment that will allow or support them.

BTW: Those "fill in the blanks" lines are for every document. If you don't know who it's for or what they need to learn, you won't write the right doc. And yes, it gets rather personal because no two developers have the same background and the same starting point in understanding your design. For example, do you need to explain the Decorator Pattern or can you just mention the name? This just reinforces the idea that a written doc is not the ideal medium for communication. If you find yourself putting 5 of these on one document - the manager needs to know this, the enterprise architecture board needs to know that, the developer needs to know the other - it should probably be 5 documents. If it's not the best and most cost effective way to communicate, do something else - grab a white board, call a meeting, dial the phone.

I bet you're thinking - My management expects design spec docs and this hasn't helped me a bit. That could be true ... we like to push you toward the "ideal" things that we use, but you may not be able to get there. I know I can't get to the point some of the other ranchers are at. If you want to guide this back to "Help solve MY problem!" feel free.
[ February 28, 2007: Message edited by: Stan James ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
One of the most important things you can learn from Agile Software Development in any circumstance is to value early and frequent feedback. Regarding writing documents for you coworkers that would mean that you ask them what they'd expect/need from a document - and after you produced it ask them whether it meets their expectations, and how it can be improved the next time.

Regarding "sections of projects", we Agilists like to break them down into very small pieces. Often a "section" (meaning an atomic piece of work, in XP called User Story) will be of the size of just a few person days of work. For those sections, the "design phase" typically will last between, say, ten and thirty minutes. In fact, most of the design is decided upon while coding, not beforehand. The reasoning behind this it that the primary function of design is to deal with the forces in source code - and that designing while feeling those forces is superior to designing while just imagining them.


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
william gates
Ranch Hand

Joined: Feb 21, 2007
Posts: 112
I think agile works best with smaller teams and with teams that seem to stick around for quite some time. Everybody at least knows what is going on or knows somebody who built a specific application or system.

But many projects I've worked on in the past became nightmares because these large systems built over the years never were documented well, if at all. And when one piece is added to another piece over 10+ years, it suddenly becomes, "where is everything and what does everything do and when there is nobody left who worked on this system it becomes one big nightmare.

It's nice if you or somebody you know built it, but the fact is, IT is about maintaining systems. I've worked on many projects for different companies where one person was the only one who knew the ins and outs of a system. There used to be more, but they all left and/or were laid off. And this person was a year or two away from retirement. Once the guy was gone, nobody from that company had a clue aboout that system or what it really does, how it works and so on. And it was a mission critical system. There are many large and small companies out there that do this.

Yeah documentation can become burdensome and a pain in the neck. But in reality, if you never document anything or barley anything, it's all find and dandy if you work on it because you built it , designed it and so on.

But the reality of IT is most people rarely stay at one place for the duration of a system. I might know class A supports class B and so on, but somebody in two years will have no clue and then without any documentation and if I'm long gone, it becomes a major problem for the business. And then IT looks like a joke to the business when it takes 6 months for new people to figure out whats going on when the fact is it could have taken a lot less with proper documents.

Yeah many people never read documentation or specs, but that's their fault.

I think agile development is great, but in the long run, if people don't document anything well, IT will look like a joke to those hiring, firing, and putting out the money.
Scott Ambler
author
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
Documentation is in fact a part of agile software development, it's just that we're really smart about it. You might find Agile Documentation to be an interesting read.

In general, the Agile Modeling Site provides some pretty good advice for modeling and documentation strategies which enable you to scale agile beyond the small teams which everyone likes to talk about. The Eclipse project is the largest agile project that I know of, and that certainly isn't being done by a small co-located team.

- Scott


<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by william gates:
I think agile works best with smaller teams and with teams that seem to stick around for quite some time.


*Software development* works best that way, no matter what approach you choose.

It's true that you can be "more Agile" when you have a colocated and rather stable team, though.

But many projects I've worked on in the past became nightmares because these large systems built over the years never were documented well, if at all. And when one piece is added to another piece over 10+ years, it suddenly becomes, "where is everything and what does everything do and when there is nobody left who worked on this system it becomes one big nightmare.


An Agile approach wouldn't hold you from producing the documents you need.

Documents do have an disadvantage, though - they are error prone, because it needs additional effort to keep them up to date. It's the common wisdom of maintenance personal that you can't trust documents.

That's one of the reasons why Agile teams work hard on keeping the code as clean and self-expressing as possible, and on providing as much of the documentation as possible in the form of automated tests (which will give immediate feedback by failing when they get out of sync with the actual system).

It's nice if you or somebody you know built it, but the fact is, IT is about maintaining systems.


Yes - in fact it could be argued that an Agile team is in maintenance mode after the first week of a project.

I've worked on many projects for different companies where one person was the only one who knew the ins and outs of a system. There used to be more, but they all left and/or were laid off. And this person was a year or two away from retirement. Once the guy was gone, nobody from that company had a clue aboout that system or what it really does, how it works and so on. And it was a mission critical system. There are many large and small companies out there that do this.


That's certainly not a good situation to be in. I'm not convinced that a lot of documents would make it much better, although possibly a little...

But the reality of IT is most people rarely stay at one place for the duration of a system.


Well, it's not as if this were a law of nature - if reality is that way for us, it's probably because we *make* it that way.


And then IT looks like a joke to the business when it takes 6 months for new people to figure out whats going on when the fact is it could have taken a lot less with proper documents.


I can't imagine a well-factored system with an extensive suite of both acceptance and unit tests that would take a competent team 6 months to figure out what's going on - even if there were no other documents at all, which of course isn't what Agile is asking for.

Yeah many people never read documentation or specs, but that's their fault.


That's a little bit too simplistic to me. If people don't read documentation or specs, that's probably because they don't feel that they get enough bang for the buck when doing so.

Blaming the people doesn't look like the most effective way of dealing with the problem to me. Perhaps we should instead take a closer look at how we can make most of the documents unnecessary, and how to improve those we still need so that people actually *do* want to look at them.

I think agile development is great, but in the long run, if people don't document anything well, IT will look like a joke to those hiring, firing, and putting out the money.


Well, I am working in a team of seven developers on a one million lines of code project, of which the oldest line is near to a decade old. We have near to zero documents (besides some UML diagrams on white boards, some basic information in a wiki etc.). I can tell you that we look all but like a joke to our management and customers since we adopted Agile practices. In fact adopting Agile practices is what enabled us to move the system to a maintainable state.
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
The value of documents outside the code may be an illusion.

I just moved teams and being the new guy on a framework that has been five or seven years in the making with major ports to different environments along the way is pretty rough. The architecture documents are a couple years old and a bit stale ... a kind word for just plain wrong. On the team I left it was my personal passion to keep the docs we had up to date. I wrote a Wiki to lower the boundaries to authoring and correcting. But I would not be surprised in a couple years to find that team in the same place as this one. It has certainly been my experience in the past. I have a fat folder full of docs that I was very proud of at the time. They were true for the day they were printed ... if that.
Devender Thareja
Ranch Hand

Joined: Jul 14, 2005
Posts: 187
Wow. That was very enlightening discussion. Thanks everybody. Agile rocks.


Devender Thareja
SCEA, SCBCD, SCJP
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
 
subject: Technical Specs, anyone?
 
Similar Threads
Advice needed -- sysadmin to enterprise developer career transition
I hate my tech lead....
Danger of Asking Co-workers Java Related Questions
how to write technical specification, is there any template?
Technical Specs, anyone?