OT: Tech Writers & Wikis
Marcus Carr
mcarr at allette.com.au
Mon Mar 19 15:29:58 PDT 2007
will white wrote:
> I'm dubious that folks in most development environments have the
> leisure to dawdle around in a wiki when they have their own workloads
> to get through. Or am I misunderstanding the charm of a wiki? It
> sounds like a mechanism to convince other people to do my work.
Wikis are currently underpowered, but they support some of the concepts
that will find their way into everyone's work sooner or later. The most
significant is probably collaborative creation of data rather than the
classic "amend, distribute, discuss" loop, where contradictory views may
take several iterations to reconcile to everyone's satisfaction. Take
the example of contract creation - a contract can bounce around for
weeks over relatively minor changes. The lawyers on both sides should be
looking at, annotating and modifying the same document, not just a copy.
There should be a full revision history of the document including
information about who made the changes and when. When both sides are
happy with the result, they should version the document with a view to
declaring it to be final.
Nearly any type of information would benefit from this approach - the
idea that you could have the engineers, the business analysts, the
technical writer and the coders all involved with specifying
requirements is another example. Perhaps you'd have the technical writer
able to edit the document and all the rest able to participate in
threaded discussions at the requirement level, but not actually able to
edit the document. In that scenario, everyone has to step up to the
plate and take responsibility. If you've had an opportunity to
contribute but have failed to do so, it's quite clear who has let the
side down.
We've been betting on that approach for over 8 years, since we started
developing PageSeeder (http://www.pageseeder.com). The problem with
wikis is that people want to create documents with more structure than
wikis support - they want a contract to contain sections that contain
clauses. Making them use wiki markup is like making people author in
HTML, but wikis are a step in the right direction. We believe that you
need to hit the XML schema that the data conforms to, not force a lowest
common denominator solution.
This explains my feelings for treating FrameMaker primarily as a
typesetting engine rather than the centre of the documentation process.
Unless Adobe are planning something dramatically different for
FrameMaker, there is a real requirement for the data to be XML and to
exist outside of FrameMaker. Of course you still need to paginate and
print your hardcopy, but only after the hard work of producing the
content has been finished. It's a great tool for producing hardcopy - I
started using it in the early nineties and have always been a fan. If
you use all of the functionality that it has though, you will not be
able to pursue options like those described above. Your data will be too
dependent on your application. A robust system needs to prioritise the
data and make use of applications, not shape the data in accordance with
the feature set of a particular application. Okay, okay, I'm off the
soapbox...
Marcus
More information about the framers
mailing list