atw: Switched topic: Modern handling of doc change records etc
- From: Peter Martin <peterm_5@xxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>, <austechwriter@xxxxxxxxxxxxx>, <austechwriter@xxxxxxxxxxxxx>
- Date: Tue, 30 Jun 2009 16:17:40 +1000
I'll leave Bob Trussler's problem to those who believe in handling everything
the old way... on paper. It's unlikely anything will change there.
For the present, this is an expansion or explanation of some of the things I've
mentioned in a response to his particular problem.
My proposition, should you wish to contradict it, comment on it, expand on it,
or just bloody ignore it, is that we keep getting locked into paper concepts,
decades after the introduction of the computer revolution, and there really are
better ways, IMHO, when it comes to IT programming and IT record keeping.
It's as though the programmers' tools for change and bug tracking and for
version control of code can only be used on code, while documenters have to
struggle on with manual updates of version numbers, detailed lists of changes
to be formatted and reformatted every time a new document is produced (I'm
thinking Word here, folks...) Some of these templates people keep using are
effectively ancient relics that ought to be put down on papyrus with an inked
stick.
It's as though program code isn't really text, or documentation text isn't
really code, and the two have nothing in common.
None of that is true. Programmers developed version control systems to keep
track of complex and frequent changes in the versions of their code. They
also developed bug and change tracking systems to track the reasons for
changes, and progress being made with them. Their bug and change tracking
systems can be linked to versions of code checked into version control systems.
They developed tools to allow for two different "checked out" versions of the
same piece of code to be "diffed" or compared, and even tools to reconcile or
merge differences.
All of these tasks can be, and ideally should be, performed for documentation,
as well as for code. A lot of places are doing it.
And you can have your choice: you can either link versions of documentation
in a version control system with the versions of the code they document, or you
can maintain doc versions in separate compartments in the same system with
"looser" links (say, only dates or release or build number) to relate them to
code.
Just as importantly, and with the same advantages as apply with code, you can
maintain documentation change control records in a bug tracking system used for
code, and maintain details of requested changes, required changes, priority
ratings, etc as well as details of authors, dates etc etc... And what you
then get, as the programmers get with their bug fixes, is the ability to search
for things like doc bugs outstanding, doc bugs of high priority, doc bugs
entered by Mary Smith, doc bugs fixed by John Doe etc etc..
If you're lucky, you also get the side benefit of seeing some of the changes
that are coming up in the code that everyone forgot to tell documentation about
(You know: "Oh, didn't we tell you we changed the whole GUI interface?")
You can peek into the future and the business of the programmers instead of
chasing your tail down blind alleys of assumptions that are out of date.
And even if you're checking in with Word documents it's even possible to check
out two versions of a Word document from a version control system and have a
"diff" comparison made up in Word to show differences between the two versions.
(e.g. one free tool is CSDiff).
And like the programmers, in most version control systems, you can even embed
the version or release number in your document and have it updated
automatically by the system.
So why do we put up with the ancient systems of badly-organised messy tables of
versions and change details etc all crammed into a document as though it's only
suitable for paper release ?
Think of it... The people who are fixing all those bugs, and matching all those
requests for change, aren't sitting down insisting on a nice Word list every
time something changes. They're tracking things the modern way. Why should
documenters be different ? If the programmers can have the convenience of
version control and database searching for things like priorities, and
outstanding issues etc etc.... why can't the documentation people have the same
convenience ? Is code holy and documentation so dirty you can only touch it if
it's wrapped in paper?
I've seen this "future" working in practice (hi Proxima and Access guys!)
It's a little messy to set up, (for a few days after you've planned it out) but
superior as hell in practice. And checking stuff in and out these days with
systems like RCS and Subversion and similar systems can all be done in a
Windows environment from Windows Explorer file viewing without any deep
knowledge of the version control processes going on.
We've even had systems running which "built" the latest version of the
documentation at the same time as we built the code.
Is it just me ? Why isn't this a lay-down misere? I suspect the answer is
that tech writers are really masochists. (Or, at heart, scribes. With quills.
Who like nice tables and things. )
-PeterM
peterm_5@xxxxxxxxxxxxxx
Ability is nothing without opportunity. - Napoleon Bonaparte
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter
To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go
to www.freelists.org/list/austechwriter
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx
**************************************************
Other related posts:
- » atw: Switched topic: Modern handling of doc change records etc - Peter Martin
