Lars Trieloff

Open Source for Tech Writing Teams

Supporting Technical Documentation with Open Source Tools

1

Lars Trieloff

About the SpeakerOpen Source Developer (Apache Cocoon, Goshaky)Book Author (DocBook-XML, published 2005)Startup Founder (Mindquarry, 2006)Blogger (http://weblogs.goshaky.com/weblogs/lars/)

Interests: Web 2.0, Collaboration, Documentation

2

Lars Trieloff

IntroductionHigh tech vendors need technical documentation

Open Source projects need technical documentation even more

Mediator between the product and the usertechnical documentation needs:

peopleprocesstools

This talk is all about process&tools

3

Lars TrieloffProcesses: Who needs

them?help us coordinate teamworkhelp us coordinate peoplehelp us coordinate taskshelp us coordinate knowledge

Conclusion: We need processes

4

Lars TrieloffHow information

workers work 5

Lars TrieloffWho collaborates in

technical documentation 6

Lars Trieloff

Activities in the Process 7

Lars Trieloff

Activities in the Process 7

learn about the user

Lars Trieloff

Activities in the Process 7

learn about the product

Lars Trieloff

Activities in the Process 7

evaluate current docs

Lars Trieloff

Activities in the Process 7

synthesize information

Lars Trieloff

Activities in the Process 7

write the information

plan

Lars Trieloff

Activities in the Process 7

create the content

specification

Lars Trieloff

Activities in the Process 7

create the first draft

Lars Trieloff

Activities in the Process 7

review the first draft

Lars Trieloff

Activities in the Process 7

write the second draft

Lars Trieloff

Activities in the Process 7

copy-editing

Lars Trieloff

Activities in the Process 7

localization & translation

Lars Trieloff

Activities in the Process 7

publish to print and web

Lars Trieloff

Activities in the Process 7

publish to online help

Lars Trieloff

Activities in the Process 7

Lars Trieloff

Management Activities 8Development of a project planDevelopment of estimates for all activitiesTracking of hours expended for all activities

cost-control, better estimates, better managebilityManage translatorsManage production checklist

Lars Trieloff

The ToolchainWe want a 100% free software toolchain to support roles and activities in the documentation

process

9

Lars TrieloffThe Basics:

Documentation FormatDocBook

established open source documentation formatlots of toolsAlternatives: DITA, Tex

Image Publishing:PNG (raster graphics) and SVG (vector graphics)

10

Lars TrieloffNext: Tools for Documentation

InkscapeGIMPXML Editors?

EmacsjEditLyxVIMPolloXerlinQuantaVEX

11

Lars TrieloffAdvanced: Team Infrastructure

Technical Documentation can learn from Software Development.

Different WorkSame ProblemsSimilar Solutions Possible

Three signs of successful software projects:

Version Control SystemsBug Tracking SystemsWikis

12

Lars Trieloff

Version ControlA safeguard for your work

nothing gets lostundo/redo for your team

Activity trackinglogsdifferential comparison

Concurrent workmergingwe are using XML, it‘s possible

Version Control SystemsSubversionBazaar, Mercurial, CodevilleMindquarry (easy to use GUI)

13

Lars Trieloff

Bug TrackingIn software development:

Bug TrackingIssue Tracking

In technical documentation:task tracking

Benefitseveryone knows what to domanagers can trackallows bottom-up-management

State of the Art:Bugzilla (Powerful, but complex)Mindquarry is a lightweight task tracker for teams

14

Lars Trieloff

WikisWhere to use

collaborative whiteboardcollaborative outlinercollaborative mindmapcollaborative websitegather information in wikis

Do not use Wikis for producing contents - It‘s authoring capabilities are weak compared to your desktop toolsSoftware

MediaWiki, MoinMoin, Mindquarry

15

Lars Trieloff

ConclusionTechnical Documentation is difficultProcesses can help making your life easierProcesses are often hard to implementSoftware for team infrastructure can helpSoftware is hard to use, too, but Mindquarry is an Open Source Collaboration Software with usability in mind

16