TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Ed wrote:
> I have been tasked with introducing "modern
> techniques" into my company,
What a strange and wonderful post! Sorry I didn't address all
your questions directly, but I hope my rambling and venting will
shed some light. I did try to embed a few actual constructive
suggestions, though.
What you describe is not a documentation problem; it's a
management problem. Documents will not solve your management
problem. Reengineering taught us that you shouldn't automate bad
processes. First you fix the process, then you automate it (or
document it, in this case).
Before creating any documents, make sure you have identified the
business problem the document is supposed to solve. A lot of
documents exist just because somebody said so. Especially SDLC
documents. Maybe a document is not the best way to solve that
particular business problem.
> Communicating current and relevant information can
> no longer be effectively done at the water cooler.
Reduce the size of your teams and chop out layers of management
until communication once again starts happening at the water
cooler. Install water coolers as needed.
> tenfold growth, from six to sixty people, and expect to
> double again this year...chaotic growth rate
umm...now this *really* doesn't sound like a documentation
problem anymore. Just wondering, what is the
manager-to-developer ratio in those new hires? How many product
mgrs/project mgrs? How many executive assistants? You see where
I'm going with this, I hope I'm wrong.
> Is there value in Use Cases when we are mainly specifying the
> layout of files, databases, User Interfaces, etc?
Use cases are valuable if you use them at the beginning of the
design phase. But if you designed the product without use cases,
then don't try to reverse-engineer them in later. Same goes for
specs.
Who exactly is asking you to create use cases for file layouts?
Do they know anything about use cases?
> The traditional documents we have always
> used...are now huge, difficult monsters.
Do to the huge difficult documents what you'd do to huge
difficult employees: Terminate them. Or at least downsize them.
Specs are instructions for creating the product. First write the
spec, then code the product based on the spec. If you want to
code first, that's fine, but then stop pretending that you need
a spec. If you want to code first, don't waste everybody's time
creating post-mortem specs just to satisfy some methodology.
You didn't say whether you had to comply with any specific set
of govt regulations. If you have specific requirements in that
area, that would change everything. I assume in the securities
business everything has to be 100% auditable. So, despite my
previous comment about flat organizations, maybe you need a
"compliance czar" who is responsible for making sure all
development meets your security and auditability standards.
Otherwise, this time next year you might be answering questions
from senators :)
Maybe you also need a top-notch configuration management expert,
who will set up systems to control versioning of code releases
as they progress through product maturity.
> This would mean that there is only one document
> (an interwoven document set) which is constantly updated.
You can do this with DocBook and CVS. This is the standard
toolset for Linux documentation. But you'll have to write in
markup...If your developers are open-source types they will
probably enjoy this.
> 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!).
If the developer who did the work six months ago isn't around
anymore, start thinking about your turnover problem.
Also make sure you aren't bottom-fishing for maintenance
developers. A lot of companies look for the lowest bidder for
this type of work. Turnover is high, and the top performers
aren't interested. Make sure you apply the right talent to the
maintenance projects, not just the new development.
It may be impossible to create enough documentation so that
"just anybody" can do the maintenance.
If you absolutely must have a document, then your methodology
must require:
1. That the developer writes the document before coding, not
after
2. That there are regular audits to make sure the documents are
up to date
3. That there are real consequences for developers and their
managers with inadequate documentation (no bonus, termination,
etc).
Here are my final half-facetious, half-cynical, half-serious
thoughts about SDLC documents: In the end it really doesn't
matter what documents are generated by a SDLC methodology. The
main thing is that they have to be voluminous, annoying, and
time-consuming to create.
Why? Becaues in mission-critical software, CHANGE is equated
with RISK. So the drag caused by the documentation is required
to increase the effort required to implement change, and
therefore slow down the rate of change. In other words, SDLC
documentation is the sand in the gears that keeps the machine
from running out of control.
good luck,
Mike O.
__________________________________________________
Do You Yahoo!?
Great stuff seeking new owners in Yahoo! Auctions! http://auctions.yahoo.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
---
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.
