1
Lars Trieloff
Open Source for
Tech Writing Teams
Supporting Technical Documentation with Open
Source Tools

About the Speaker 2
Open Source Developer (Apache Cocoon, Goshaky)
Lars Trieloff
Book Author (DocBook-XML, published 2005)
Startup Founder (Mindquarry, 2006)
Blogger (http://weblogs.goshaky.com/weblogs/lars/)
Interests: Web 2.0, Collaboration, Documentation

Introduction 3
High tech vendors need technical
Lars Trieloff
documentation
Open Source projects need
technical documentation even
more
Mediator between the product and
the user
technical documentation needs:
people
process
tools
This talk is all about process&tools

Processes: Who needs
4
them?
help us coordinate teamwork
Lars Trieloff
help us coordinate people
help us coordinate tasks
help us coordinate knowledge
Conclusion: We need processes

How information
5
workers work
Lars Trieloff

Who collaborates in
technical documentation 6
Lars Trieloff

Activities in the Process 7
Lars Trieloff

Activities in the Process 7
Lars Trieloff
learn about
the user

Activities in the Process 7
Lars Trieloff
learn about
the product

Activities in the Process 7
Lars Trieloff
evaluate
current docs

Activities in the Process 7
Lars Trieloff
synthesize
information

Activities in the Process 7
Lars Trieloff
write the
information
plan

Activities in the Process 7
Lars Trieloff
create the
content
specification

Activities in the Process 7
Lars Trieloff
create the
first draft

Activities in the Process 7
Lars Trieloff
review the
first draft

Activities in the Process 7
Lars Trieloff
write the
second draft

Activities in the Process 7
Lars Trieloff
copy-editing

Activities in the Process 7
Lars Trieloff
localization &
translation

Activities in the Process 7
Lars Trieloff
publish to
print and web

Activities in the Process 7
Lars Trieloff
publish to
online help

Activities in the Process 7
Lars Trieloff

Management Activities 8
Development of a project plan
Lars Trieloff
Development of estimates for all activities
Tracking of hours expended for all activities
cost-control, better estimates, better managebility
Manage translators
Manage production checklist

9
The Toolchain
Lars Trieloff
We want a 100% free software
toolchain to support roles and
activities in the documentation
process

The Basics:
Documentation Format 10
DocBook
Lars Trieloff
established open source documentation format
lots of tools
Alternatives: DITA, Tex
Image Publishing:
PNG (raster graphics) and SVG (vector graphics)

Next: Tools for
11
Documentation
Inkscape
Lars Trieloff
GIMP
XML Editors?
Emacs
jEdit
Lyx
VIM
Pollo
Xerlin
Quanta
VEX

Advanced: Team
12
Infrastructure
Technical Documentation can learn
Lars Trieloff
from Software Development.
Different Work
Same Problems
Similar Solutions Possible
Three signs of successful software
projects:
Version Control Systems
Bug Tracking Systems
Wikis

Version Control 13
A safeguard for your work
Lars Trieloff
nothing gets lost
undo/redo for your team
Activity tracking
logs
differential comparison
Concurrent work
merging
we are using XML, it‘s possible
Version Control Systems
Subversion
Bazaar, Mercurial, Codeville
Mindquarry (easy to use GUI)

Bug Tracking 14
In software development:
Lars Trieloff
Bug Tracking
Issue Tracking
In technical documentation:
task tracking
Benefits
everyone knows what to do
managers can track
allows bottom-up-management
State of the Art:
Bugzilla (Powerful, but complex)
Mindquarry is a lightweight task
tracker for teams

Wikis 15
Where to use
Lars Trieloff
collaborative whiteboard
collaborative outliner
collaborative mindmap
collaborative website
gather information in wikis
Do not use Wikis for producing
contents - It‘s authoring capabilities
are weak compared to your
desktop tools
Software
MediaWiki, MoinMoin,
Mindquarry

Conclusion 16
Technical Documentation is difficult
Lars Trieloff
Processes can help making your life easier
Processes are often hard to implement
Software for team infrastructure can help
Software is hard to use, too, but Mindquarry is an Open
Source Collaboration Software with usability in mind