[FM Discuss] DocTrain Report

[adam hyde]

Doctrain East
My first Doc conference.

I was on the train between New York and Boston for my first taste of a
Technical Writers conference. The nature of which I could only guess. I
had my first tech writer in the flesh just a few months earlier - and
now I was attending the DocTrain East event to do a keynote speech about
FLOSS Manuals.

On the train I felt that my presentation was second guessing the
audience as I had no idea what they would think of wikis, open source,
collaborative content, open content, remixing etc...luckily I didn't
present until the third day of the conf so I had some time to get to
grips with the situation. Below is my impressions of the sessions and
general atmosphere of the event.

First up, an explanation of DocTrain. Its an event put on by festival
entrepreneur Scott Able. Scott is truly a master of events - As a
speaker I have attended a few tech events with a ticket price in the
same range ($1000 USD) and they have always been rather large formal
affairs. The success of Doctrain is that it is a small size and pretty
informal affair. I found everyone really friendly, and like Wikimania,
people were very generous with their information an interested in
projects that were on the periphery of their practice.

The first day was workshops. I was really curious about this as I wanted
to know what tools the 'Technical Writing' sector used and how FMs tool
kit sat in juxtaposition. You can see a full list of sessions and
presenters here :
http://www.doctrain.com/east

I attended the 8.30 (early!) workshop on MadCap Flare
(http://www.madcapsoftware.com/). 

Day One, Session One : MadCap Presentation

Mike Hamilton, one of the founders of MadCap, was a very slick
presenter. Actually all the presentations were very professional and to
the point. MadCap software evolved out of a 'first generation' of
desktop documentation writing tools called 'RoboHelp'. Funnily enough I
had used RoboHelp when I was working as a manager of tech departments at
Dutch ISP XS4ALL. RoboHelp had been brought out by Macromedia and after
some internal conflicts, as is common with takeovers, the old dev team
left within a year and set up MadCap. I had a brief feeling of DeJa Vu
as this is what has just happened in the free software world with TWiki
- the developers did not buy into the vision of the 'steering'
organisation and left to set up their own project
(http://www.nextwiki.org/). Its interesting to see similar social
processes influencing the development of both proprietary and open
development. In other words - everyone, please be nice to Aco! ;)

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 ;)

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.

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.

So, MadCap itself looks like Microsoft Word. Actually it looks like MS
Word with about 3 other sets of toolbars and 4 split windows. It really
made my eyes hurt just looking at it. There were some interesting
features but I lost interest quite quickly as this approach for
interface development felt very old school. I realised in the process of
watching the demo that I hardly ever use interfaces that are this
complex. I also realised that learning an interface of this complexity
was designed to trap the user into a state of persistent reliance. If
you learn this software the idea of learning another with similar
complexity is a headache - so you don't. Its very much similar to the
argument that people don't switch to Linux because of the loss of
productivity incurred while learning a new way of doing things. 

On this level I felt frustration at this very strategic proprietary
approach. The session was also a reminder that Open Source developers
aren't the only ones that need to learn something about user interface
design.

Also, because of the proprietary nature of the project it is not
possible to translate the interface. Madcap is a very mature suite of
softwares but only available in 4 languages. If the code was open, or
even if the architecture was transparent, the development of other
language versions would be easier.

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.

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.

MadCap has its own file format based on xml (FM uses xhtml - a subset of
xml) and can output to multiple formats including PDF and xhtml (like
FM). They have an interesting method for inserting text
'snippets' (previously written sections) into a body of text. We also
can do this but not nearly as easy. MadCap uses CSS for styling content
(as we do). It uses basic H1, H2, H3 (etc) heading structures for
content (as we do). 

After 3 hours of the 'all you can eat' interface I felt very frustrated
by the overly complex interface and I had the feeling that only 20% of
the people in the room would use even half its features. I could be
wrong of course - it wasn't a survey so no need to fact check me on that
one ;)

MadCap Flare sells for $900 USD per single user license. If you buy the
'suite' of MadCap software its $1300 per license.


Day One, Session Two : Controlled Authoring
This was a presentation by Berry Braster. Berry is a Dutch guy living in
Texas and working for Tedopres, a consultancy. This was about how to
reduce technical concepts to simple language. Infact there is a science
to it that I was not aware of. Essentially there is a legacy of reducing
language which has evolved to the current standard of 'Simplified
Technical English' (STE) - a lexicon of 900 words that are recommended,
2000 words they ban from use, grammatical rules (57 of them), and an
approach to writing some of the main tenets being:
* 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"

STE evolved over 70 years, first finding roots in the aerospace
industries. The idea with STE is that it should make text clear and
succinct. The way they sell this to organisations is also to outline
that reducing word count reduces the number of words when translating
documents and this saves $$$

There is also the argument that reducing ambiguity reduces risk (esp.
when writing manuals for airline industries etc).

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.

Over coffee I spoke with a linguist, a translator, and some experienced
tech writers about STE and it seems it is a fashion, particularly useful
for product manuals, but there was mixed verdicts on its over all use.
Interestingly, the linguist was very much in favour of it, but the
translator felt that compressing language this way loses meaning. The
old guard tech writers saw it useful within specific contexts.

However I could see some of my own writing improving if I kept these
things in mind but at the same time I think many of the rules are quite
intuitive and don't need to be consciously forefronted when writing.

There are various tools for parsing text and highlighting banned words,
checking grammar etc to comply with the STE rules. One little whizzy
interface item I saw that was nice was a inbuilt dictionary that would
highlight words that were not in the agreed lexicon and recommend
synonyms that were in the accepted word list...we could certainly build
this into FM if there was a need for it by any contributors... but I
think we would not expose that functionality to everyone for fear of
overburdening the writing process.

End of day one! I pretty much went to my room and took the insights I
had gleaned about how Technical Writers see the world and altered my
presentation to fit.

Day Two. 

I skipped the first keynote. It was a product push by one of the
sponsors, and after seeing a similar move at Wikimania I saw it for what
it was and opted to sleep in (the rooms also had very nice big
baths :))))

Day Two Session One : Creating a Clear Message from Icons and STE
This was an interesting session. Lotte has made some very nice icon sets
in SVG that I have yet to fully integrate into FM. You can see some
examples here:
http://en.flossmanuals.net/icecast
http://en.flossmanuals.net/Audacity

If anyone wants these icons let me know. I will also make sure we have a
pre-set of icons ready for the forthcoming circumvention Book Sprint.

The presenter, John Watkins, was not able to make it so a colleague of
his stepped in. Unfortunately i didn't catch his name, but he was a very
entertaining presenter. He had an interesting trick for soliciting
feedback from the audience, essentially he would ask a question and the
first to answer it would get a block of chocolate. After the first
question people were pretty much shouting over each other to get the
goodies. hehe...I was one of those cynical guys scowling at the back of
the room ;) Not a tactic that would work on me, but it was effective.

The first part of this presentation was to talk about icons to convey
messages across differing cultures. His main points were:
* avoid text at all times
* avoid using bodies or parts of bodies in icons
* avoid using animal shapes
* avoid regional specifics (such as displaying writing as a left to
right activity)
* avoid politics, race etc...

I was left to ponder what kind of product icons would reference
politics...

These are pretty straight forward rules. He used McDonalds as a case
study (sigh). The big M wanted to highlight nutritional values (the
irony) of their 'food' on the packaging (maybe 'of' their
packaging ;)...and hence they need icons. What was interesting is that
they wanted to iconise some pretty abstract ideas such as 'calcium' and
'protein'. You can see an example here:
http://images.usatoday.com/money/_photos/2005/10/25/mcdonalds-nut-chart-180.jpg

What is also interesting is that part of the strategy to make sure the
icons work is to get them used as much as possible - to expose the icons
to the public so they learn what they mean. Hence the M made a very
liberal license for using the icons - essentially anyone can use them
for free. It was an expensive excercise - apparently they had to check
13,000 issues to do with the use of the icons in varying cultures and
language sets before they settled on what they have.

Next he talked about the use of language. He emphasised a lot of what
Barry Braster had talked about in the presentation about STE and someone
recommended a book 'Writing Global English' by John Kohl.

then it was coffee....

Day Two Session Three : Social Media
Rich Maggiani gave a 1 hour overview of 'web 2.0' and 'social media'
practices. It was a 101 Intro to this subject. Essentially a roll call
of the most well known sites and services. I like his approach to
keywords "What does matter, is what it does not what it means". He also
had an interesting thesis on why 'social networking' sites work :
"...because your neighbourhoods don't". Don't know if I agree with it,
but interesting perspective.

One very interesting moment came which reminded me of the times we are
in - he showed the site for Wachovia Bank and was commenting on some
customer interactions functions it had...and it was pointed out taht
Wachovia Bank no longer exists, it was a victim of the current
overloaded leveraging of loans....I think Rich had taken those screen
shots less than a week before.

Richs' session wasn't really for me but for the Tech Writers. It was
apparent he was introducing new ideas to those present and there was
some scepticism with comments like "but who cares about this stuff?!".
There is an obvious generational cultural divide but that was
interesting to observe. Rich did a good job of introducing people to the
ideas without scaring them off.

Day Two Session For : Agile Writing
Now...being a NZer I know a lot about rugby. Its genetic. I did not know
however that rugby serves as a metaphor for a practice in proprietary
software development. They call a rapid development cycle for code
(which very much looks like our Book Sprints) 'Agile Development'. In
the Open Source world it is also referred to Code Sprint (which is where
the name Book Sprint comes from). In this 'Agile Environment' the team
is called a 'Scrum'. A Scrum is also a particular phase of play in
rugby. 

So...this stole my attention for a moment, wondering how far I could
extend the metaphor (not far as it happens). 

A 'scrum' is a group of people that meets for one month (an
'iteration'). In the scrum are developers and possible a tech writer.
The group (sorry I have to drop the rugby analogy) works out what they
need to do in 1 month. They work in one room so the can speak to each
other immediately about issues. They do the work. They release it. Thats
the story. 

The aims of the iteration is concrete and specific and does not deviate
once set. The idea is to raise productivity in short dev cycles. The
writer must work out their role in this dynamic and consider if they
should come in late, stay to learn about the dev (of course there will
not be much to document early on), or come after the process is finished
and write the docs. 

In the group is also one 'obstacle remover' - a person there to remove
obstacles so everyone can just get on with it. The usual size of the
group is 5-6 people. 

They also employ several tools including :
* 'burn down charts' (plotting completion of a project)
* 'daily stand ups' (meet first thing in the morning, stand up, give a
status of your progress)
* debrief at the end to see how to improve the process
* present the work at the end 

All in all it sounds like our Book Sprints EXCEPT that the Book Sprints
are more fun. Thats not a trivial thing. I believe that FM has an
advantage here in that no one 'has' to be in a sprint. They come because
they have a passion for the subject. This can lead to a wonderful
dynamic. It is also important that people have fun. My experience has
been so far that just being there to work on something you are
passionate about with people who share the same passion is fun in
itself. However I really try to make sure that Book Sprints also have
some things that are fun which do not involve screens. In the
forthcoming sprint for example I hope we will all be able to go skiing
in the Catskill Mountains. 

The presenter, Christine Sigman, then presented her thoughts on why the
Agile Dev process is an advantage over longer more planned development
paths :
* shorter release cycles are more motivating
* more visibility of each persons work within the team
* less planning documents and hence more autonomy for team members
* greater focus can be brought to smaller issues
* less structure is liberating for the participants

Christine also underlined that the role of a tech writer in this kind of
environment is to document the code, and the practice is less suitable
for interface documentation. Slightly off topic - but one of the people
in the audience put his hand up and said in their company they fired all
their testers and replaced them with technical writers and since then
their product has massively improved. It made me wonder if it might be
useful to start working alongside free software developers to provide
more feedback on the softwares while documenting them.

The day ended with free drinkies in the showroom where all the
technology was on display. I looked around and asked lots of questions
about the tools. I am sorry to say that none of them impressed me and
they are all too expensive. But then again, I don't need to use these
tools so I can't give much depth to my criticism. Suffice to say I saw
one online system which was 'like' FM - DocZone 'lite'. It was badly
designed, awful to use, and cost $200 a month per user.

That night was Obama night. I retired to my room after drinks to watch
the 30 minute infomercial that Obama had paid for on all channels. It
was lame - well produced but lame. Still, interesting to see.

Day three : My big day.

Right...so After the Obama blahblah I sat in the bath and reworked my
presentation. I think I got it close to where I wanted it. I don't like
to over-prepare for presentations but I do like to make sure the story
has flow. My general rule is to throw anything out that is unnecessary
and stick to a pre-planned path but not rehearse the way to get between
the points on that path. I feel it keeps me on my toes and I hope it
sounds spontaneous - and there is nothing like standing on stage without
a rehearsed keynote to keep you focused and spontaneous ;)

So, the first two presentations where interesting. One about the North
American Technical Writers Association (STC) and one about general
principles of managing large scale documentation project infrastructure
development. I made no notes, my apologies, I was more concerned with
being focused for my presentation. 

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. The main things I wanted to do was :
* highlight that community docs are quality docs
* show the architecture of FM
* highlight the whizzy features (Book Store widget, remix, embed api)
* talk about the design and why we think its important to have a good
looking site
* highlight the differences between Fm and the structure of a typical
wiki
* seed the idea that a free documentation sector can enrich the
Technical Writing world

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

I will post others if I see them. I did get lots of good feedback
afterwards from people at the event, and made some very interesting
contacts. In addition Scott Able invited me to the next DocTrain to hold
a mini Book Sprint.

I missed the first session as there wasn't much for me and so I did some
other work. The first session I went to was after lunch.

Day Three Session Two : Quality Content through Collaboration
I missed the session "Creating Quality Content with Open Source Tools"
through bad planning, but I understand it was an introductory session
and Scott Nesbitt talked alot about FM.

However the session I attended was interesting. Interesting because I
thought it could lend some insights into how quality could be enhanced
in the open wiki world of FM. However the discussion really talked about
how to harmonise review processes using Word Documents and PDF. Ugh.
Thats like trying to make a bath out of straw. Too much work...why not
have a system online? I didn't get the obvious inattention to working
online when talking about collaborative processes.

As for the tips - they were obvious :
* be accurate
* publicise your docs
* make them error free
* write with the user in mind
* make sure the docs are complete

I enjoyed the presentation because it was clear and illustrated a
perspective in the Tech Writing world that surprised me a little - in
some quarters the idea of collaboration seems to be new...

Day Three Session Three : Leveraging the DITA Community
Ok, one keyword that I have not mentioned but was EVERYWHERE in the conf
is DITA. It is a file format, based on XML and structured in such a way
that it is a much hailed cure for all Technical Writing woes. The idea
has such a strangle hold on the sector there was a booth in the showroom
with a rotating slidehow that illustrated '10 things they don't tell you
about DITA'. It was quite negative and the tone might not have been out
of place in a republican television ad but it seemed well out of place
in a tech showroom.

However..there are many people aboard the DITA train. I spoke to some
writers about it and the opinion varied. Apparently DITA is good for
'structured writing'. This is something I could not tell you about. It
sounded a little religious actually, like there is procedure for writing
documents that conforms to the DITA format and ultimately makes your
documentation more usable and reusable. Hmmm...maybe. I can't say for
sure, but file formats by themselves don't cure anyones problems -
especially if they are not implemented in the software in a consistent
way. This exact issue, as it happens, was the kick off for Bob Doyles
presentation. He had tested DITA files created by several softwares by
opening the resulting file in other DITA authoring softwares. It seems
only one could open all of the files.

This was some time ago, but it seems to me the DITA format needs wider
integration within the tools Tech Writers use, and the open tool kit
needs, ironically, to be better documented. This later issue is what the
mini Book Sprint in the next Doctrain will be focused on (DITA is an
open format and the open DITA tool kit is open
(http://dita-ot.sourceforge.net/).

So, Bob talked about DITA. He was obviously a local hero - there are not
many people that can make statements like "I have done everything I can
for the tech writing community" or "I am leaving tech writing to spend
time in Information Philosophy, a field I just invented" and get away
with it. But get away with it he did. Bob, after all, wrote the very
first Desktop Publishing application on the Mac (Mac Publisher) and
several other interesting initiatives. Hes a good guy, and his grand
statements actually seem appropriate. He is also big on DITA and he went
through this a lot. However I need to know more about the format before
I can really parse his statements.

Day Three Session Four : Should you call it a Wiki? 
Stewart Mader was next up. He wrote Wiki Patterns
(http://www.wikipatterns.com/). He is an evangelist for wikis. I looked
forward to this session the most and got the least from it. It was very
introductory and I don't enjoy hearing evangelists at work because they
necessarily gloss over the facts. But he was there to preach and preach
he did. Perhaps I should have left as his sermon had an effect on the
unconverted but to me it was just a stream of generalisations about how
wikis can do anything. Sure they can do a lot but there are caveats. 


So that was it. I took the late train back from Boston to NYC and
arrived home at 4am.

....

I should mention that before I got to the conf I had a great dinner with
Andy Oram (OReilly/FM Advisory Board - Andy is also working on something
for FM which will be very interesting but I will leave it up to him to
discuss it when he is ready) and spent the evening hanging out with Mako
Hill from the FSF etc. So I saw some people I already knew which was
nice and made some more new friends at the conf that now understand and
support what we are doing. 

It was a very worthwhile conf, and I look forward to the next DocTrain.
In the meantime its the Book Sprint (Nov 9-16) and then presenting FM in
San Francisco (http://www.aspirationtech.org/events/devsummit08).


adam


-- 
Adam Hyde
Founder FLOSS Manuals
http://www.flossmanuals.net