[FM Discuss] DocTrain Report

Sun Nov 2 19:16:31 PST 2008

Hey Janet,

Wow...cool comments :) Many thanks for fleshing out and giving depth to
my newbie overview.

I was wondering if you think we can tempt many Tech Writers to FM to
contribute? I found many people interested but then I also found in the
sessions there were many that were hesitant to do anything wiki-like or
go near free software...its a diverse profession as you point out but I
hope we might be able to find the right arguments to convince more TWs
to participate...

adam

On Sun, 2008-11-02 at 20:56 -0600, Janet Swisher 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.
> 
> > 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
-- 
Adam Hyde
Founder FLOSS Manuals
http://www.flossmanuals.net