[FM Discuss] DocTrain Report

[Janet Swisher]

Hi Adam,

Thanks for the conference report. I was wondering how things went at
DocTrain. It's very interesting for me as a tech writer to see an
outsider's perspective into the topics that TWs talk about amongst
themselves.

On Sun, Nov 2, 2008 at 1:19 PM, adam hyde <adam at flossmanuals.net> wrote:
> Day One, Session One : MadCap Presentation

> So...some key words. Madcap does :
> Topic Based Authoring - essentially the same as what we do. Writing
> content within self contained chapters. We have a keyword now so you can
> tell people FM is a 'topic based authoring' platform ;)

I generally think of chapters as being longer than topics. That is, a
chapter often contains multiple topics. For example, if you have a
chapter on frobnitzes, which describes all the things you can do with
a frobnitz, then each of those tasks would be a separate topic. FM
encourages you to make chapters self-contained, but it doesn't require
that you start a new chapter for every topic (neither does Flare, for
that matter; DITA does).

> Single Sourcing - using one source of text files to output to customised
> versions of documentation. This is not quite what we do, remixing could
> be classified as this but I think Single Sourcing really is referring to
> customisation of content on a paragraph or sentence level.

"Single sourcing" means many things to many people. For some people,
it also covers what MadCap is now calling multi-channel publishing. In
MadCap's terms, you can reuse content at multiple levels: topics,
paragraphs, sentences, or even words (e.g., when you "rebrand" your
product for a particular customer or market). It lets you have outputs
with overlapping sets of content, such as for different audiences
(users/admins) or platforms (Mac/Windows/Linux). You can do this at
the topic level with remixing if you keep your topics sharply focused.

> Multiple Channel Publishing - this we do! Outputting multiple formats
> from one source. We, for example, create books, PDF, HTML and the Live
> Manual api from one source (the wiki).
>
> So we do about 2.5 out of the first keywords I learned ;)
>
> Apparently Topic Based Authoring is catching on. It really struck me
> that people that are used to writing for the web do this intuitively.
> Although there might be interlinking, writing for the web hardly ever
> means you write sentences like "in the next chapter you will
> discover..." etc. So I was struck quite early on with a cultural
> difference between my perception of where most of the Technical Writers
> are coming from and where the FM community has come from.

I think there is a "generational" effect in the TW community, which
has more to do with the companies people work for than with their age
or experience level. These things are just common sense to me, but
apparently, some people still haven't been exposed to them, due to the
backwater where they've been working. I also see it when programmers
or other non-TWs sit down to write what they think of as a "book"
(because they're using Word to write it); they imagine that the reader
will read it linearly, start-to-finish, the way they wrote it. This is
almost never true for software manuals, even if they are printed as
books.

> As I understand it, from the show of hands in the room, FrameMaker (yes,
> it still lives!) is king in this sector and MadCap is a far away second.

FrameMaker and Flare focus on different purposes. FrameMaker is for
long documents (books); MadCap has a separate product called Blaze
that competes on that front. Flare and RoboHelp are for online help
and secondarily output to print format. I see FLOSS Manuals as
somewhere in between those two targets.

TWs expect "online help" to look like MS HTML Help (.chm), with a side
pane that displays a keyword index and full text search function in
addition to a table of contents; they also expect it to integrate with
the application being documented, so that the user can click a Help
button in a dialog box and see the corresponding help topic. FM's HTML
output doesn't quite match that model. If you are interested in
producing an output like that, there is a Javascript-based help format
that is open source, called OmniHelp
(http://www.omsys.com/dcl/omnihelp.htm).

> The other very strange thing about MadCap is that the demo started with
> an introduction to the help files for the application. So MadCap is
> there to help write text based documentation...and the files they
> recommend to use to learn how to use the software are....video files...
>
> Now, I don't believe you should stubbornly follow the open source mantra
> to 'eat your own dog food' but...I would think if you want to sell a
> documentation software then you should recommend the documentation that
> was written using the software. Otherwise its an admission of sorts that
> you are in the wrong business. On this note - FM needs to address the
> role of video files or slide shows sooner rather than later.

It's a matter of choosing the right tool for the job. Demo videos are
very useful for introducing a user to a software tool, which is
probably why they were highlighted in the talk. Flare does also have
text-based online help, no doubt produced with Flare, which is what a
user will turn to when they need to remember "How do I do X, again?"
The video is to tell them that they can do X in the first place.
MapCap has another tool, called Mimic, for doing demo and simulation
videos.

The only open source tool for this purpose that I'm aware of is
CamStudio (http://camstudio.org/).

A non-open solution that you might want to look at for ideas is Jing
(http://www.jingproject.com/), because it's integrated with a video
hosting service, (http://screencast.com/).


> Day One, Session Two : Controlled Authoring
> * use words that have just one meaning
> * if a word has multiple meanings use only one meaning and use that
> consistently
> * use a maximum of 25 words for descriptive text
> * use an active voice
> * use a maximum of 20 words per sentence for instructional text
> * use 6 sentences per paragraph
> * "get rid of the 'nice to know', and write about the 'need to know'
> items"
>

> I thought that this methodology was interesting but it also strikes me
> that this would produce very formal text. So although the rules are very
> useful I think I would not like to see FM manuals losing this informal
> 'friendly' style that is in a lot of the docs. Also, I think that the
> way to achieve clearer texts is a social process for us not a technical
> rule-set. If we added these kind of rules for writing I think this would
> deter contributions. It would be better just to let people write in the
> style they want to write and then rely on other contributors that enjoy
> editing to come in after them and clean it up. Its for this reason too
> that I think having Technical Writers, like those at the conference,
> present within the FM community really adds to the dynamic of the
> community and the docs produced.

I think some of the principles of STE can be helpful guidelines for
FM, but should not be enforced as rules. For example, it can be
difficult for translators and non-native speakers (who are often
essentially translating on the fly in their heads) if you use the same
word as a noun and as a verb. Similarly and unfortunately, idioms and
jokes are often difficult to translate. Short, active sentences and
short paragraphs are good, but there are always exceptions. Passive
voice is often used (see!) when the actor is unknown, already
understood, or irrelevant.


> someone
> recommended a book 'Writing Global English' by John Kohl.

I'll take a look at that one. I've got a copy of "The Elements of
International English Style" by Edmund Weiss (which is a bit cheaper
than the other on Amazon).

> Day three : My big day.

> So I got up on stage and went through the presentation. I can't remember
> what I said, it was a trance, but I think I got the message across
> clearly.

> So...I can't give a review, you will have to ask someone else! I have
> seen this one write up of my presentation :
> http://www.dmncommunications.com/weblog/?p=644

Congratulations! Sounds like the talk went well.


--Janet