[thelist] Re: A Different POV

[jay.blanchard at thermon.com]

 >The ability to write and document sites/apps/code that your successor
 >can maintain and extend definitely has ROI implications ... So why do we
 >run into so few folks that understand that?

The reason(s) that I encounter so much is that people who design/develop
web sites for a living are;

a. People who have never written code before and have not yet learned about
standards or documentation. As an old (and just got older yesterday)
computer geek I was taught documentation from the first line of Fortran.
However, many, many of those in our current industry are self-taught (not
that there is anything wrong with that!) but rarely does a 'Learn HTML in
24 Hours' book say much about documentation practices, save for a brief
foray into indentation and a brief swipe at placing comments in the code.

b. People who have written code before, but hated the restraint of having
to justify or explain everything that they do, or saw documentation as a
waste of time. After all, if it works, why tell  you how they got it to do
that? So they turned their coding loose into an area where no one agreed
about anything, but since stuff worked it was all good. And nobody really
paid attention.

I am sure that there other types of people who make up this group, these
are just the ones I run into. I also very rarely find anyone who writes
code who likes to perform documentation duties, including myself. Designing
and coding is much more fun and satisfying than explaining/justifying how
or why you did something. And it's definitely more fun than distilling the
client's wishes into readable "scope of work" documentation. But the
upside.....

Perhaps I should write an article or series about how to make documentation
as painless as possible while explaining its benefits. Would it be
preaching to the choir? Hmmmm...[*scratching chin*] perhaps a documentation
standards thing similar to webstandards.org? <sarcasm>Nah...it would
require too much documentation!</sarcasm>

Steady on my soapbox on a rainy Monday.

Jay

<tip type="documentation" author="Jay Blanchard">
Basic Documentation should have the following sections;
Definitions - All terms that may not have an immediately recognizable
meaning in this context.
Scope of Work - An outline of what it will take to accomplish the core of
this particular project. If it ain't in this scope, charge extra for it.
Workflow Models - Descriptions of interfaces and where they go, what they
do, and what the end result is. (i.e. User clicks on link, logs in, and is
presented with an interface offering these choices. When he/she clicks on
this choice he/she is presented with this information and these choices,
and so on, and so on.)
Back-End Information - Database tables (in detail), administrative
passwords, etc.
Milestone List (Project Tracking) - can be as simple as having a list of
things which needs to be done, and a place to put the date of completion.
Could have spots for the developer and the client to initial.
Potential Mods/Adds for the Future -
This is the place to identify things seen during the development process
that can be improved, but would be considered "scope creep' if we just went
ahead and did them.
Also include flowcharts, data diagrams, workflow diagrams, etc.
</tip>