SDLC Documentation Help Requested

[Ed Manley <EManley -at- Solutionsplus -dot- com>]

Hello TechWirlers,
I haven't been on this list in quite a while, maybe years, so I am glad to
have the opportunity to return. Thanks to all who participate here.

I have been tasked with introducing "modern techniques" into my company, a
software development shop. By "modern techniques" I mean software
development process improvement, particularly in the areas of requirements
elicitation and management, and documentation for the software development
lifecycle.

In preparation for this task I have been studying Agile Modeling, the RUP
(Rational Unified Process), eXtreme Programming, UML (the Unified Modeling
Language), learning to use things like Class Diagrams and Use Cases. Each of
these areas offers tools, methods and techniques for improving the
development process, but none of them deal with documentation with any depth
or clarity. 

There is a lot of talk about "just enough" documentation, but no definition
of what "just enough" might be for shops like mine.

So, I bring my questions to you. Thanks in advance for any help. There are a
lot of questions here; please answer those you can. I hope to discover
enough interest about this to get a good thread going, because I know quite
a lot of development shops struggling with these same questions.

We are the developer of the Securities industry's leading Corporate Actions
Notification system, a Visual Basic system running on NT and supporting
multiple databases (Oracle, Sybase, DB2, etc.) In the last six years we have
experienced tenfold growth, from six to sixty people, and expect to double
again this year. As a result of that chaotic growth rate process and
methodology have taken a back seat to getting a quality product out the
door. Based on industry acceptance, that worked.

Now we are feeling the pain of outrunning our processes. Communicating
current and relevant information can no longer be effectively done at the
water cooler.

The traditional documents we have always used, the Business Requirements,
Solution Approach, Functional Spec, Technical Spec and so forth, are now
huge, difficult monsters. We do most all of our documentation in MS Word,
using Visio for things like Data Flow Diagrams and not much else. We have
tools like Adobe Photoshop and RoboHelp, but nobody knows what to do with
them.

We use PVCS Tracker for issue management, but use no tools for Requirements,
Testing, etc. We will buy tools only when we have a solid process or
methodology and believe that we can enhance our capabilities with those
carefully chosen tools. We will not likely buy a tool and try to mold our
process to it. Why? Right after being assigned this task I instituted a
full-blown sixty-day enterprise-wide evaluation of the Rational Enterprise
Suite. wow. Our tool adoption is gonna be somewhat more careful in the
future. That's no slam at Rational - they have a great product, came on site
and installed it for free, really treated us great - it was just way too
much too soon - my fault, not theirs, resulting in my current need to more
fully understand documentation and its details before trying to implement
it.

Since most of our work now and in the future will be in enhancements to this
system, we need to thoroughly understand what we have. There is little or no
documentation extant (code and deliver leaves no time for documenting!), so
we are increasingly missing something important when we design an
enhancement. A bug fix may very well break two other things, since we no
longer know all the linkages and relationships.

We don't have, but I am creating, a proper data dictionary (We use
Embarcadero's Schema Viewer if we need details of a table or data element).
I want to maintain and publish this in a better format, but don't know of
one. Do you?

Given that we are making changes to a system we don't fully understand, our
enhancement estimates and time lines, even our enhancement solution designs,
are often way off.

So, we have two main needs: 
to "properly" document the enhancements we are designing, whether at the
customer's request or internal, to more accurately plan development,
and 
to modify our documentation process so that we have a methodology going
forward that assures "just enough" documentation. 

We most likely will expend minimum effort on going back and documenting the
system that exists; more likely we will let our new methodology for
documentation gradually expand as we touch legacy code when enhancing it.

My questions to you are:
What documents should be used in this type of environment?
What is the purpose of each?
What is the content of each?
Who writes it?
Who maintains it?
What artifacts are used? 
Is there value in Use Cases when we are mainly specifying the layout of
files, databases, User Interfaces, etc? 

We may have an enhancement - let's say, to add the ability to import SWIFT
data files, for example, wherein change to our system is minimal...we
already import numerous file types, so this just means defining the import
file, adding it to the import code, adding the file layout to our database
schema, adding the import selection option to one screen, write some code to
do the import, and maybe three lines of text in the User Guide mentioning
that SWIFT files can be imported just like any other file. Ten days of
coding for a single developer (I am just making up a scenario and numbers
here....they don't have to make sense to make my point).

What documentation does that need? Who/how/when does it get written? How is
it communicated so that a maintenance developer working a bug fix next year
can find the details of how this import works (or why it doesn't!).

What if we have an enhancement that will take four developers six months to
do? That's quite common. How do we keep the necessary info at the
appropriate level of detail available to whoever may need it?


Lastly, I envision creating an online documentation system, where the reader
can start with a high-level description and drill-down ever deeper to
whatever detail they need. This would mean that there is only one document
(an interwoven document set) which is constantly updated. Version Control
issues would be reduced to document archiving, as the only available
document would be "live" and shared online. No longer would we have ten
versions of a Functional Spec floating around on people's hard drives!
Anyone who printed parts of the document would be required to discard it in
a week, and to make all notes online. Need a User Guide? print the top level
of the documentation, which contains all the functionality description (Use
Cases). Need a Functional Spec for one module? See the next level of detail.
Need Technical Specs? Drill down one more layer.

I guess that's a pipe dream, but if any of you has ever seen a single-source
documentation paradigm like that please let me know!


Ed Manley
Senior Business Analyst
Solutions Plus, Inc.
Suite 250
3595 Grandview Parkway
Birmingham, Alabama USA 35244
205-439-5764 Voice
205-439-5769 FAX
emanley -at- solutionsplus -dot- com 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.