RE: Writing structured content [recap]

Subject: RE: Writing structured content [recap]
From: "Chris Vickery" <cvickery -at- arenasolutions -dot- com>
To: "Mike Starr" <mike -at- writestarr -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 25 Jun 2007 09:15:30 -0700

Mike Starr: "And if we cannot incorporate cross-references into the
actual topics, do we then lose that ability in the finished document? Or
do we add
cross-references as elements of the finished document that are not part
of
the topic database?"

You have to add cross-references at the assembly level for your
document. In DITA, you'd add such relationships at the DITAMAP level,
both with topic families and with relationship tables. If you include
cross-references inline in your text, the linkend topic may not be there
in all your maps and you'd have a broken link.

That's sound logic for Help and HTML output, because you don't want your
reading navigating away in the middle of a topic. It is a little
strained, though, in the BOOKMAP output. You end up with a PDF with a
list of links at the bottom of each topic. I am having to redo my manual
to address cross-references in this way. Of course, since we don't
publish a printed manual, the PDF can be seen as an electronic document
anyway, and having the links appear at the ed of each topic would be
fine.

My worry is about those Cro-Magnons who actually print the manual out :)

Chris

-----Original Message-----
From: techwr-l-bounces+cvickery=arenasolutions -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+cvickery=arenasolutions -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Mike Starr
Sent: Monday, June 25, 2007 6:23 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Writing structured content [recap]

However...

Once we've written hundreds or even thousands of discrete topics, we now

require an organizational database to make these topics available for
use.
Each topic must then be associated with metadata that describes the
topic
itself so we can understand specifically what the different topics are
about
and when it's appropriate to incorporate that specific topic in a larger

assembly of topics. The formation of that metadata into a database will
require careful planning in order to make the database readily
searchable. I
can envision the metadata often requiring far more storage space than
the
topic text itself.

Having said that, the availability of the discrete topics is still going
to
require an analytical process by a content planner (formerly known as a
technical writer) who's developed a sufficient amount of product
knowledge
in order to select appropriate topics for the subject matter based on
the
audience requirements. The greater the number of topic authors, the more

difficult the analytical process becomes as the content planner will
have to
familiarize herself with the actual content of the available topics in
order
to make rational selections.

And if we cannot incorporate cross-references into the actual topics, do
we
then lose that ability in the finished document? Or do we add
cross-references as elements of the finished document that are not part
of
the topic database?

Mike
--
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Website developer
Graphic Designer - Desktop Publisher - MS Office Expert
Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
Email: mike -at- writestarr -dot- com - Web: http://www.writestarr.com

----- Original Message -----
From: "Gordon McLean" <Gordon -dot- McLean -at- GrahamTechnology -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Monday, June 25, 2007 8:00 AM
Subject: RE: Writing structured content [recap]

> It might well be that a set of guidelines is the starting point, and
that,
> in fact, the 'rules' of writing content that can be reused aren't all
that
> much different from what we have now.
>
> Understanding the structure is part of it, and yes that will include
> understanding when NOT to include some information... But presuming we
are
> past that point, maybe there ISN'T a need for a training course in
this
> area, maybe it is purely down to understanding the structure and
following
> a
> set of simple guidelines.
>
> But I'm not sure, nor convinced, it's that "easy". As Fred says, at
some
> point, once structure is understood, and the writer knows what NOT to
> include, the content that will be used has to be written. I presumed
there
> was an approach to this type of writing, breaking the thought model
out of
> chapter/book mode and into chunk mode, but maybe there isn't. Maybe it
is
> just a set of "dos and donts"..
>
> One thing is for sure, this thread has certainly pressed home the
> importance
> of nailing the early requirements and fully understanding the
structure of
> our documentation.
>
> Gordon

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats
or
printed documentation. Features include support for Windows Vista & 2007

Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as cvickery -at- arenasolutions -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit
http://lists.techwr-l.com/mailman/options/techwr-l/cvickery%40arenasolut
ions.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.


Follow-Ups:

References:
RE: Writing structured content [recap]: From: Gordon McLean
Re: Writing structured content [recap]: From: Mike Starr

Previous by Author: RE: FRIDAY: Unlikely athletes?
Next by Author: RE: Employment question
Previous by Thread: RE: Writing structured content [recap]
Next by Thread: Re: Writing structured content [recap]


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


Sponsored Ads