[FM Discuss] DocTrain Report

Mon Nov 3 04:42:32 PST 2008

On Mon, Nov 3, 2008 at 8:56 PM, Janet Swisher <jmswisher at gmail.com> wrote:
> 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.

Gotta come out of lurking to suggest that a mention of 'single sourcing'
might prompt a reference to the book 'Single Sourcing' by Kurt Ament

http://www.infotektur.com/projects/index.html

I find it brilliant. The book is small, the concepts simple, a
reflection of deep understanding resulting from decades
of experience.

Thanks,
Kent

>
>> 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
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>