Articles / What's Wrong With The Way T…

What's Wrong With The Way Things Are Done?

During the past 10 years, I have been involved with several software development projects, and most of them turned bad along the way. Some of the projects I have been involved with started badly, and I was one of a group called in to attempt to correct things, or I was one of the developers who was involved for the whole duration of the project. These are some of my observations about the state of things and what might be done to correct them.

Current development trends are much the same as they were 10 or more years ago. Perhaps 10 years ago, not everyone had a PC, but most of the concepts are the same. A single person is responsible for a static set of documentation handed out to various individuals, all of whom will be ultimately responsible for the final product.

In the last 10 years, the static document has become more dynamic, with almost everyone having access to the program used to generate the document, and the document is typically emailed, rather than existing as a "dead tree edition" hard copy passed out in a meeting, but there is still one central person responsible for the "golden" version of this documentation.

This collection of documents is emailed to all individuals involved in the design, as the design evolves. The designers will have meetings to discuss the design, and make changes to the design. Some features will seem obvious, and not be written down, and others will be written in painful detail.

Once development is started, a copy might be emailed (or a scratched-up hard copy given) to the developers as they are involved, and usually one or, worse, multiple versions will be put in a public place, making the current one difficult to determine. The developers may not understand the text as it is written, or other knowledge the designers had won't adequately be conveyed to the developers in the document, and key features will not be coded correctly. Usually, inadequacies will be corrected in prototypes, but the documentation will not cover this.

After the project goes to QA (all projects have some form of QA, even if it is the marketing department who plays with a prototype), some of the documents deemed important will be given to QA so they have the ability to judge the quality of the work the developers created. Some of the test plan will be devised by the designers (if they happened to consider that testing would be part of their responsibility), and this knowledge may be covered in various documents given to the QA department. Subtle details that were given to the developers by the designers will not be covered in the documentation. Features and design updates will be designated as bugs by the QA department, since these changes might not be covered in the design documentation.

Users are given instructions based on what the technical writer understands the product to do. Generally, the product will be what the designers originally intended, if enough time is given to the project. If the project was time-limited, there will be substantial changes, and features just left out. Subtle changes made during development will not be reflected in the original design documents for various reasons (including resource constraints), and these changes may (though this is unlikely) be reflected in the documentation.

Support is typically left out of all documentation. Maybe they will have access to the original documentation, but probably not. Various tester notes will have been completely ignored, limiting support's ability to do even basic troubleshooting. Normally, because the support people are thought to be bothers to developers, they will only be able to call the developers under dire circumstances (which will be the norm, since they have no idea how things are supposed to work). The developers end up late on the next project since they spend so much time supporting the current project. (If they spend no time, then the company goes broke, and the issues all go away).

It seems support organizations are used to not having resources to support them, so they don't bother asking. When some is available, it is completely ignored, and trouble keeps festering. Development accuses the support organization of being dumb, and the support organization accuses the developers of being uncooperative. Self-fulfilling prophecies. It has to change.

Other Problems

If the key person leaves, there is no golden set of documentation. Organization of documentation is usually up to an individual. Parts of one project overlap other projects, and changes in one may affect others. The originator of the design documentation understands this (and maybe others do to a lesser degree, but usually, key knowledge is lost when this individual changes positions).

If a new person is added to a project, she must get all the same knowledge everyone else has. That can mean email from multiple individuals, archives of related email, and a host of meeting notes. Organization of all this information will be quite difficult for her, or it will take an excessive amount of time for someone familiar with the project to organize this information and present it to new people after the fact.

When the project is to be revised, many of the "why" decisions will have to be addressed. Why did the project not get this feature? Why does it do things this way instead of that? This knowledge is gone unless it is recorded somewhere. There may be no way to capture this information after the fact, since people move on or just plain forget. Rarely will one person have all the answers.

Sometimes, the goals are not clear. Sometimes, the whole reason for doing the documentation, the project, or whatever is some other agenda.

What Can Be Done?

The best way for documentation to be done is in a more dynamic sense. All of the people involved in the project usually have a computer to use to manage the documentation. Turn responsibility of the documentation over to the whole group. Put the files in a central repository where everyone can manage them.

HTML doesn't yet offer the same formatting abilities as a word processor, but it provides easy access during development. It allows people to read any document anytime (or can be password protected, if necessary), and editing can be done offline or online, in sections or as a whole. (Early in the design, word processor documents are usually a hindrance, since people concentrate on format over content, and content is very important until the details are finalized.) HTML also allows easier crosslinking of public documents, perhaps enhancing sharing of ideas (and code) between projects.

Change meetings to electronic discussions where the "wild ideas" are captured, and someone can say "we did that because...", rather than having multiple people suggest the same change and have it rejected because of some subtle reason, multiple times. Having electronic discussions will also allow people to participate after the fact by reading the notes and being able to question the participants.

Documentation needs to be a continuous process. If the project leader is aware of details such as a User Manual and begins thinking about the users of the product, the quality may be better. Internal products may not need marketing literature, but it might not be a bad idea to at least think about how to sell the change. If the developer is aware of testing documentation, some "scary" part of the code can be incorporated into the testing plan, and the product can be more thoroughly tested and made more reliable.

Once the project goes from design to development, the developers and designers can add clarifications and corrections to the design. As the design goes from development to QA, the changes (and the reasons for them) can be made clear, and non-problems will be handled as non-problems. Once the product is finally documented by a technical writer, all the details will be nearly correct as designed. The support people will have the opportunity to ask for "features" to help them do their job.

Once the project is "finished", the designers, developers, and QA should get together and add to the document, outlining the pros and cons of the current design, the details that were desired, and the pitfalls from the user's perspective, as well as from the developer's perspective. This document would be the start of the next revision's design document, even if that project is months (or years) away.

Properly tracked, changes can be easily managed. I'll argue that the changes won't need to be tracked if everyone shares the success of the project. If the people involved with the project are truly participating at the same level, there won't be any need for finger pointing or tracking who did the bad thing.

The Culture to Make it Happen

The only way this will happen is if everyone buys in. Designers have to give up their home directory. Their work will have to be put in a central public repository. There will have to be a sysadmin (or tools) available to deal with daily changes to permissions for this repository (designers are the only ones who can change until development has started, etc.).

Developers have to realize they are part of the documentation process. Many developers feel that documentation is up to the tech writer and that designers don't know coding. This is mostly correct, especially since tech writers don't know coding, either. The tech writers need something to start with. Everyone needs to help everyone. Developers change jobs, and everyone knows you cannot always look at the code to get the full details of the project. Tech writers usually write user documentation, and coders write coder documentation. The coders can start with the design documentation and the tech writer can start with the coder documentation, each creating a public document for a specific target.

In extreme cases, everyone's C: drive should be made read only, and Word should be removed from everyone's hard drive. At a minimum, Word, Visio, Excel, and PowerPoint email attachments should be outlawed. The key to making all this happen is that all data is in a central place and can be updated by appropriate people at any time. Once a document is emailed or printed, it is obsolete, and changes are not reflected in old email.

People will argue that the above tools are ubiquitous, and if the files are put on a shared drive, everyone can access them and update them. I would agree that the tools are nearly ubiquitous and nearly shareable. For odd reasons, people sometimes share things with various read/write bits set so that only the work group can share items, or only they can read them. Visio isn't on everyone's desktop, especially if they aren't using a Microsoft operating system. Until there are tools that are more ubiquitous and sharing can be more automatic, minimizing the non-ubiquitous tools will be the best way to interact with the documentation.

Things Needed to Make Change Easier

Once the culture has adopted these suggestions as a good idea, there need to be tools in place to make this happen. The documentation repository should exist, with the tools to allow all users to use it. There need to be electronic discussion tools available. There need to be documentation templates. Old project documentation should be made available to allow current products to be updated.

Many tools are available to make a system like this happen, including Lotus Notes and various chat programs. Each has benefits and drawbacks. Programs like Lotus Notes and Exchange, being proprietary, require everyone to have the program and don't leave room for extensions or flexibility in their use (e.g., the use of other clients). Chat programs have no longevity; if the discussion has moved beyond a subject, typically, it will have to be brought up again.

Since most of the Internet was built on email, newsgroups, and the Web, and these tools seem to have longevity, I suggest that they would be the tools to use. Email mailing lists can be used to call attention to new things, including updates to documents, questions that a newsgroup is discussing, or other issues. The newsgroups would be the electronic discussion tools. The Web would provide the golden documents, incorporating issues discussed on the newsgroups and in email. Another tool that may be useful is WikiWikiWeb, which allows full collaboration on Web pages by anyone with a browser (see PhpWiki).

When a new project is started, templates for all the documentation must exist. There should be templates for all types of documentation, and the project leader should begin by putting the title of the project in the document repository and at least blank templates for all documents. All the documentation should include:

  • Design Documentation
    • Timeline
    • Budgets
  • Programmer Documentation
    • UML/Object design
    • Physical/flow design
  • QA Plans
  • User Manual
  • Marketing Literature
  • Support Notes
    • Troubleshooting basics (i.e., flow design, test accounts, etc.)
    • Machines/passwords
    • Contact phone numbers

Obviously, not all products will need all these documents, while some will need more. Having access to templates covering a minimal set of knowledge for most projects will make getting documentation easier. Final documentation for a small project may include some parts of many of the templates in a single document, and a large project may have multiple instances of various parts of these documents broken into subprojects.

Conversion of current documentation will be difficult. This is a one time cost, however, so once done, it may be considered an investment. The difficulty will be to collect all the information that isn't available in the current form to be collected, just as a new user would have to collect and organize the information.

Other Thoughts

Much of this is brought about by frustrations with current systems, and many of the ideas are quite utopian, inasmuch as radical changes to current culture are almost impossible to accomplish, but doing nothing will produce the least risk and the least rewards. Adopting any of the changes here with a complete buy-in will provide a better world. Without complete buy-in, these ideas will certainly create chaos, and have the potential to make the world a worse place.

These radical ideas are not wholly mine; other people have suggested change, include the EXtreme Programming (XP) group at Chrysler. This group actually advocates less documentation, but in a way different than this document suggests. They do advocate developers coding tests that can be used by other groups.

A similar way of thinking is advocated by Chuck Musciano's Don't Cramp My Style comments. Tools are tools; they don't build products. They can be used to build products, but only people build products. Communication is the cornerstone to good products.

Certainly, the Open Source movement has tainted my thoughts. Knowledge and information should be free. There shouldn't be an owner to parts of a project, and no single individual should be allowed to hoard any of this information. That feeling must include respect for everyone involved in the project. There are responsibilities that everyone in the project assumes, and everyone incurs the same risk. Not everyone has the same abilities, and people's strengths must be reckoned with their weaknesses (nerds don't have interchangeable brains).

Of course, there are ESR's Cathedral/Bazaar writings, in which he quotes Brooks, Chapter 9: "Show me your [code] and conceal your [data structures], and I shall continue to be mystified. Show me your [data structures], and I won't usually need your [code]; it'll be obvious." I want to change this to "Show me your code and conceal your design docs, and I shall continue to be mystified. Show me your design, and I won't usually need your code; it'll be obvious." :-D

Where I am Right

Some people seem to be listening to me. I suggested a Wiki for development communication and documentation, and it seems to have taken off. This is a great improvement. The Wiki is maintained by everyone in the project, and it is being regularly updated. A couple of different projects are currently in development using the Wiki, as well as a couple of finished projects. Ownership was relinquished (although I seem to be the support organization for the tools), and developers and designers update the same sets of documentation. (PhpWiki and pwiki) are quite robust, so the system seems quite seamless. The buy-in has happened, which adds to the success. I haven't polled everyone, but I don't think too many people who have used the Wiki would switch back to the old way.

One improvement might be the addition of a transition. Once a project's development is complete, the Wiki has stopped. The "final" documentation (user manual, support notes, etc.) needs to be quantified and written. This documentation can (perhaps should) stay in the Wiki, but it needs to be done. Perhaps the templates described above could be incorporated into the Wiki so when a new project is started, is has links to all this documentation. This is where a tech writer could come into play, a professional to manage the documentation. This person could insure that all the needs for these "final" documents can be gathered, then could be the follow up documenter.

I tried to make it available to support, but they aren't interested. This is a whole 'nuther article -- how to get a support organization to cooperate. When I can quantify the issues there, I'll write it.

Recent comments

30 Aug 2001 18:47 Avatar zorg3

dia . Re: if not visio, then?
there is an open-source alternative to visio.

Dia supports UML, standard flowcharts, and a few other diagramming systems. it's fully user-extensible, and has XML support -- including SVG graphics support, so its data-files should be usable even from an MSFT OS.

30 Aug 2001 18:00 Avatar zorg3

looks like a start at building some project-documentation software
political as it might sound, this is another example of why it's great to be on the open-source side of the fence, and to have a public forum here at [fm].

i haven't had an opportunity to develop software in a commercial setting, but have been wanting to develop something for keeping the work more organized when doing so; it could be used on open-source projects, but the commercial focus is a plus. sketched out some plans, but didn't have a sense of how it actually works -- the devshop dynamic. this editorial has plenty of information fo getting a handle on it.

i guess i'm looking for something more formal than a wiki.

for what it's worth, here are some project ideas for discussion:

- KOffice has XML support. maybe that could be used with some server-side XSLT, for generating HTML out of whatever categorized documents.

- the wiki method, of making a page editable by all the users of the wiki, isn't a bad idea, but seems like it could get out of control.

- a single author, or an author-group, should have sole write access to any given document. this is more like the "cathedral" than the "bazaar", but some formality isn't neccessarily bad.

aegis might be worth looking at, regarding this. it has a system of "developers", "administrators", and "reviewers", each having certain privelages and certain roles in the development of a project.

- a web-based forum approach could be used, for letting the team-members provide feedback about the project.

with a case like sourceforge, the comments from the developers might be made so as to be hideable from the everyday visitors. the same could be done with the admins' discussions, which could optionally be hidden from the non-admin developers.

- for the writing: keep it off the web. a browser-based form doesn't offer nearly as much editing power as a real text-editor.

for the reporting: keep it on the web, at least in an archival sense.

- the w3c has been using a sort of document-management system.

- i don't know if they have any special apps for it; there might be a web-based interface, for moving things between the various stages of a document draft.

- the draft process is explained at

- the whole thing is explained at

- there are probably different types of documents that would be passed through the system.

this, here, is an example of something like a whiteboard doc , or some sketches. [it's a "note" but that seems too general of a term for identifying it.]. it might or might not lead to a more formal document, or it could lead to multiple documents, on different topics.

- with version control on the docs, each document could have multiple versions within one draft-stage [linear branch, or release-tagged file].

- a search engine could be used, on a per-project basis, with further organization for filtering out "everything not a note" or "everything not a final draft". it could have support for a semantic search, perhaps based on XML meta-data, but it should at least have a simple interface, like google.

- each document could have a set of 'notfication hooks' assigned to it. some could be automatic, as with an "author group" or a "reader group" redeiving notification about significant changes to the documentst that are related to their work; others could be added by developers, at will [e.g.: by developers working on different projects in the same company].

- some things come up when you're in the middle of writing source-code.

every file in the source-code would need to be linkable from a document within the system, with something for sending the reader to a specific line/column number

- maybe:
1) tree-based indexing, with ~symlinking ability
2) something quicker than a web-browser, for navigating the tree

- the system would need support for footnotes, though the footnotes should not be heaped-up at the bottom of a displayed document. they should be available as seperate files

if any of this sounds useful, there's sourceforge for the new OSS projects, and is an alternative that might connect the project with some funding.

i could use some regular input from folks who've had more experience than i have, with development oin commercial and OSS projects.


related: , "reflective software engineering"

27 Jun 2001 07:40 Avatar Ilan

The diagnosis is easy
it's changing people and the way they do things
that's the hard part. As a person in QA (I hope to
eventually finish school and do usability design)
, I've seen my share of botched projects (albeit
commercial, but this also applies to open source).
In order to solve many of the problems you bring
up, programmers/project managers/companies need to
totally rework their mindsets and ways of doing
things. You need to essentially start from user
and work your way backwards (IMHO, I consider it
to be forwards). The current paradigm which is
failing places users at the bottom.

Steps for success

0. Know what market you are shooting for. Don't
listen for a second to marketing people who say
"we develop the market as you develop the
software". People have needs. People who meet the
needs of those people who have needs make money.
People who aren't sure what people have what needs
and don't give any people anything of what they
need don't make money. If these idiots make money,
it's because they were smart and sold their stock
options right after the IPO

1. Analyze the users of the software. What are the
tasks they need to perform? What kind of computer
background do they have? What is their work
environment? How long is the average time spent
using the software? You have to understand that
the success of the software is the success of the
user performing their task in an efficient and
fairly painless manner. Failure to accomplish this
is failure of the software.

2. From the data collected from #2, design the
interface. Probably 99% of all programmers could
not design a usable interface if you put a bloody
gun to their head. Unless you have the 1% of
programmers who probably do understand UI design,
hire a UI designer. Studies show that every $2
spent on usability design saves $100 of tech
support costs later on. The UI designer studies
what was learned in step 1 and will come up with
an initial design, which will be augmented with
user testing as the coding starts to produce
working stuff that can be tested. It is absolutely
critical you start usability design before code is
written. If you skip this step and write the code
first, I guarantee you that programmers won't want
to make the necessary changes to ther interface
because they're afraid it will add bugs. Not that
it actually will, but that's what they think and
they will do absolutely anything to avoid
improving the UI. Another advantage of designing
the interface before coding is that the
documentation people already have something to
work with. It's at this point you should have the
technical writers start writing the manual. They
already have the basic idea of how the user will
interact with the software.

3. Then go in with your UML modeling. Your dia,
your viso, your ridiculously overpriced Rational
Software. Divvy up the necessary tasks accordingly.

4. Force programmers to comment like crazy. Even
when they don't want to. Also, document each
change and why it was done thoroughly. One of the
most bug free pieces of software on the planet is
the software that drives the Space Shuttle.
There's volumes upon volumes upon volumes of Very
Large Books (tm) stating what exactly they changed
and why they changed it. Follow their lead.

5. Only add features when people request them, and
then only add them if there is a good reason why
you should add them. Maybe they want an extra
feature because something confused them and
they're not making use of something that is
already there. In such a situation, improving the
manual and online help would make more sense than
adding another feature. Never add features that
aren't related to a users task at hand. And above
all, never let programmers add features because
they think they are neat. I know this sounds harsh
and it probably won't win me many friends on
freshmeat, but I've seen way too many square radio
buttons and half-assed implementations of
something you'd find in Photoshop. David K. Every
of Mackido fame has a saying "there is no such
thing as a free feature". This saying can have
multiple meanings, but I think the most
significant one is that when you add features, you
add more menu selections, more toolbar buttons,
more entries in help screen, and other
mental/visual crud the user has to sort through,
making them less productive. If software doesn't
make you productive, there is no point to using a

6. If you have a really good marketing department
and mind share of point-haired bosses who know
nothing about IT (like a company in Redmond
Washington that shall go unnamed) , you can ignore
the first five rules.

31 May 2001 23:31 Avatar tommyb

Re: Communication yes, chaos no

> While this is generally good stuff, I must
> disagree with throwing the design documents open
> to continuous tinkering by all. If the design is
> changeable by anyone at a moment's notice, you
> have no design.

Everyone should be treated equal, there should be roles and
responsibility. If a coder decided a requirement was too hard
and deleted it, that would be a coder not following their role.
I certainly wouldn't want a designer re-indenting my code.

> We still need to have someone in charge of the
> design. Hoarding is bad, but ownership is good.
> The thing is, the documents should not be owned by
> *any* of the designers. Go back and read _The
> Mythical Man-Month_ again, and look carefully at
> the role of the project librarian. Code isn't the
> only thing that goes in the library; design
> documents belong there too.

If the project has a librarian, then yes, they can shepherd
the documentation. Most projects don't have anyone,
except maybe the designer keeping the documentation
together and organized.

> You can still have the approved versions of the
> documentation *available* to everyone -- this is
> good. But a gatekeeper and sender-of-warnings is
> needed to preserve order and allow people to think
> without having to check for changes every hour.

Obviously if the design is changing every hour, it isn't
ready for coding. E-mail, and/or newsgroups can be
used to warn or discuss major changes, and their

The current situation where there is a document handed
out, and your start coding to it. Two days later a
new document is handed out, it looks the same, but
somewhere in 35 pages there is a change (no they
didn't use change bars, that'd be too easy, besides
they make the document look messy). Then about
release time one of the designers looks at your
user interface, and says they changed the second
screen, and moved it to 4th screen. You ask who
and when, and he shows you a copy of the design
document dated a week after the one you are using.
They didn't ask you to the meeting to discuss it
'cause your were behind in coding, and they figured
you'd get done quicker if you kept coding instead of
going to the meeting. (I am not making these up
they have happened!)

> A point I looked for but perhaps missed, is that
> *everyone* who is expected to contribute to the
> product should be involved with the design
> documentation. Not in the design itself, but in
> the crafting thereof. Designers are solely
> responsible for the design, but they should have
> to hear the concerns of the other players as they
> do their work.

Including the users, and the support groups. Absolutely,
this is very important.

31 May 2001 16:39 Avatar suitti

Yes, and it works.

In 1987, I worked in a mostly Unix shop that
incorporated most of these
procedures. Project documentation and notes, with
some discussion
were aided by local netnews groups.
Articles were set to never expire.
The equivalent of a shared drive
(NFS) was used for other documents - including
feasibility studies,
design documents and user manuals. The source
code repository
was in SCCS.
The techniques and procedures were also used for
Windows and Mac
projects. Here, Unix was used as the accessible
server with backup.

These days, I might still use netnews, but I might
be tempted to
use a forum that allows arbitrary attachments.

Further, I'd use CVS instead of SCCS - since the
edit -> update -> commit
cycle effectively gives you line oriented locking,
rather than
file oriented locking. For projects with more
than five people,
this is nearly a requirement.

Many technoheads have a reputation for being
nearly illiterate
in natural languages. I've met people who all but
pride themselves
on never writing documentation. This requires buy-in.
In some cases, I've volunteered to write
documentation for
other developers. For example, when the
documentation must
be in English, and some developers know it mostly
as a second
or third language, and I want it to be accurate
and readable,
I'll do it. It's not that I don't have my own
work to do.
But it helps that I touch type.

Things that are still difficult remain. I've yet
to see a
system where a deployed database (the data) has
been properly
archived, translated, tested and documented. Web
sites suffer
from this also - if one thinks of web pages in the
same sort of
way that one thinks of RDBMS data.

One of my main complaints about Fred's classic
book is that
there's so little evidence that anyone has read it.

This is a minor issue compared with people who
don't bother
to use tools to make things better. Spell
checkers, web page
checkers, web site checkers, RDBMS tuning
features, etc.


Project Spotlight

Kigo Video Converter Ultimate for Mac

A tool for converting and editing videos.


Project Spotlight


An efficient tagger for MP3, Ogg/Vorbis, and FLAC files.