Download - Open Source For Technical Writing Teams
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