Open Source For Technical Writing Teams

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

Slide 2: 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

Slide 3: 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

Slide 4: 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

Slide 5: How information 5 workers work Lars Trieloff

Slide 6: Who collaborates in technical documentation 6 Lars Trieloff

Slide 7: Activities in the Process 7 Lars Trieloff

Slide 8: Activities in the Process 7 Lars Trieloff learn about the user

Slide 9: Activities in the Process 7 Lars Trieloff learn about the product

Slide 10: Activities in the Process 7 Lars Trieloff evaluate current docs

Slide 11: Activities in the Process 7 Lars Trieloff synthesize information

Slide 12: Activities in the Process 7 Lars Trieloff write the information plan

Slide 13: Activities in the Process 7 Lars Trieloff create the content specification

Slide 14: Activities in the Process 7 Lars Trieloff create the first draft

Slide 15: Activities in the Process 7 Lars Trieloff review the first draft

Slide 16: Activities in the Process 7 Lars Trieloff write the second draft

Slide 17: Activities in the Process 7 Lars Trieloff copy-editing

Slide 18: Activities in the Process 7 Lars Trieloff localization & translation

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

Slide 20: Activities in the Process 7 Lars Trieloff publish to online help

Slide 21: Activities in the Process 7 Lars Trieloff

Slide 22: 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

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

Slide 24: 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)

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

Slide 26: 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

Slide 27: 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)

Slide 28: 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

Slide 29: 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

Slide 30: 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