Single-Sourcing - Follow-up as promised (fairly long)

Subject: Single-Sourcing - Follow-up as promised (fairly long)
From: Maritza van den Heuvel <MaritzaV -at- stt-global -dot- com>
To: " (TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM)" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Sun, 29 Feb 2004 11:00:56 +0200

A couple of weeks ago, Lyndsey Amott started a thread on single-sourcing. I
piped up saying that wouldn't have been able to manage our current release
(coming out on Friday, thank God!) with its numerous help files and printed
manuals on my own without single-sourcing. I was even accused of bragging.
;-) I promised a detailed report on my workflow and the way the tool I use
handles single-sourcing ... I've worked on this post on and off since then.
Things are almost done on this end, so I should have some time in the coming
week or two to follow any thread that may arise. That is, if I manage to
wade through the backlog of about 300 odd TWRL posts in my mail box!

Here goes, FWIW. Use it, don't use it. ;-)

***
Workflow
-------------
I'm a single tw for a small startup totalling about 30 - 40 people.
Development and distributed sales staff included. When I started a year ago,
the company had already invested in an authoring tool (AuthorIT - basically
bought a single Workgroup license). One of the pre-sales/training guys had
been doing documentation up to then. So I inherited a set of documents -
fairly well-written, but showing no use whatsoever of the single-sourcing
features built into the tool. In my first release I didn't have time to
learn the how-to's myself, and it has taken me the rest of the year (using
the tool about 50% of my time) to start delving into all the available
functionality.

So, what's my release process? The usual: start with the business and
functional requirements, install the alpha and start figuring it out! I'm
also fed change notices from the development team via our feature and defect
tracking system - a little check box and a few paragraphs about a
change/feature help me to verify that I'm not missing anything.

My basic documentation workflow (content only) is as follows:

1. Before anything else, create a new version of the help file/manual that
you're working with (Version Control). The old version becomes redundant
and read-only. However, its children (potentially even embedded help
files/manuals) stay active until marked redundant individually.
2. Move through the new version in any order you like - linear, conceptual,
whichever suits your product and development cycle - and identify objects
that have changed/need to change.
3. Make new versions of only those objects (information topics, graphic
objects, hyperlinks) that need to change. Since the other objects from the
previous version remain the same, they're reused in the new version.
4. Plug out the redundant versions of objects and plug in the new versions.
5. Publish the new version to the required format.

If there are layout changes for the new versions, another step comes in to
play:

1. Identify and change only the styles, templates and media objects that
need to change.

One short step ... but it takes careful planning and thinking, because of
the interdependency between the different styles, templates and media
objects.

That's the global workflow. Then there are specific single-sourcing features
of the tool that make step 3 above easier - or at least help you limit
changes to very specific objects, instead of having to make the same change
in 10 different places!

Hierarchy of objects
-----------------------------

As mentioned, AIT uses a hierarchy of interdependent objects that control
the format and layout of your published result. An informational object
("topic") is based on a template (i.e. Chapter, Section, Normal or anything
you'd like to define). This template may again be based on another more
global template and inherits properties from it's parent. The
template/templates are again based on a media object that is set up for the
media you're publishing to.

While authoring, you use built-in styles (or create your own). These styles
map to equivalent styles in your output templates (a .dot for Word) and a
CSS for HTML-based output. Styles can be based on one another and inherit
properties as well, just as in Word.

The high-level "book" (the global container for all your topics) is also
based on a template that defines things such as whether it should have a TOC
or not - this template can also include the standard front and back material
for your docs, so its all inserted the moment you base a book on it.

Finding your way around these objects is probably the most daunting part of
working with AIT. But you don't have to modify anything - the preset
properties give you a very good, fully working published results in all
formats ... My first superfast release used the defaults only and I'm not
too ashamed of those docs. ;-)

Reused topics & Embedded topics
-------------------------
Full topics can be reused as is, i.e. simply included in the TOC of any book
object. But you can also embed topics into other topics. A topic can be a
sentence or a few lengthy paragraphs. So, if you have a set of documents
that use some common content, you can write smaller generic topics and embed
them in all the locations where they are used. The final container topics in
Book A and Book B wind up being composite topics that use a number of
embedded topics.

The beauty of this is that when changes are required, you make them once and
all container topics are updated without any further effort from your side.
Saves time, but also ensures consistency - you don't have to remember where
else you have to make changes. AIT takes care of that for you.

Variables
-------------
For single words or phrases that are used in a variety of books or topics,
but that may have different values. If for instance, you have an application
suite and the product name changes depending on the combination of
applications bundled for a client, you define a variable called <product>
and use it wherever you refer to the product name. Before you publish the
book/books for the client, you assign the right variable for the particular
context. This way you can use exactly the same content, but have tailor-made
output.

Variables are also used as autotext entries ... I have one called <car> for
"central authoring location". Saves me keystrokes and prevents human error.
Not unique to this tool, I know, but enhances the other single-sourcing
features tremendously.

Modular book approach
---------------------------------
You can have any number of book objects containing any number of topics and
file objects. You can mix and match and publish these books, or sub-sets of
these books depending on the nature of the application or the client's
needs.

Release states
---------------------
You can assign states (or "statuses") to topics and objects to keep track of
the writing cycle for a release. The defaults are states like "Edit review",
"Released", "Draft" etc. I have expaned mine to be more detailed since I
wanted to track the single-sourcing process more closely. My release states
include:

Modified in version - new functionality
Modified in version - cosmetic
Modified in version - changed functionality

I can export the TOC of a book to an Excel sheet, where I can quickly
calculate basic stats on the work that has gone into a release - handy for
management reports! I'll be doing my stats for the current release sometime
next week once the release is out, so if anyone's interested to see the
percentages, let me know off-list.

Publisher
--------------
A major advantage of course is the publisher. Content and format are truly
separate and the changes you make to the one don't effect the other. Once
you've done all the writing/rewriting, you publish to the format you need,
and away you go.

Database
-------------
If you've wondered while reading this how the myriad of objects is managed?
A database. AIT's library structure is the frontend for an underlying
database (Jet/SQL). None of the technical management is my problem. The
database takes care of that for me. It also allows me to create users and
profiles and to control access to all objects in the libary. Perfect for a
multi-author environment (which is where we're heading, if I can convince
the powers that be that all our system docs should go into the library too).
But apart from a little bit of system admin, all I have to do each day is
log into my library and start working!

All in all, I think this approach is a definite documentation solution. XML
lends itself to single-sourcing too, but it doesn't take care of the object
management for you, and you have to get your hands dirty creating DTD's and
XSL's. Which is not much different from creating and modifying templates, I
suppose. But it's definitely not as user-friendly!

***
Maritza van den Heuvel
Technical Writer
http://www.stt-global.com
-------------------------------------------------------

The contents of this e-mail and any accompanying documentation are
confidential and any use thereof, in whatever form, by anyone other than the
addressee for whom it is intended, is strictly prohibited. Views and
opinions are those of the sender unless clearly stated as being that of STT.




Previous by Author: Re: Developing 150-page docs in MS Word XP
Next by Author: Re: "If the docs are too good..."
Previous by Thread: Documentation Revision Tool
Next by Thread: FWD: Quiet workplace


What this post helpful? Share it with friends and colleagues:


Sponsored Ads