Open Source For Technical Writing Teams

Slideshow Transcript

1. Slide 1: 1 Lars Trieloff Open Source for Tech Writing Teams Supporting Technical Documentation with Open Source Tools
2. 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
3. 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
4. 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
5. Slide 5: How information 5 workers work Lars Trieloff
6. Slide 6: Who collaborates in technical documentation 6 Lars Trieloff
7. Slide 7: Activities in the Process 7 Lars Trieloff
8. Slide 8: Activities in the Process 7 Lars Trieloff learn about the user
9. Slide 9: Activities in the Process 7 Lars Trieloff learn about the product
10. Slide 10: Activities in the Process 7 Lars Trieloff evaluate current docs
11. Slide 11: Activities in the Process 7 Lars Trieloff synthesize information
12. Slide 12: Activities in the Process 7 Lars Trieloff write the information plan
13. Slide 13: Activities in the Process 7 Lars Trieloff create the content specification
14. Slide 14: Activities in the Process 7 Lars Trieloff create the first draft
15. Slide 15: Activities in the Process 7 Lars Trieloff review the first draft
16. Slide 16: Activities in the Process 7 Lars Trieloff write the second draft
17. Slide 17: Activities in the Process 7 Lars Trieloff copy-editing
18. Slide 18: Activities in the Process 7 Lars Trieloff localization & translation
19. Slide 19: Activities in the Process 7 Lars Trieloff publish to print and web
20. Slide 20: Activities in the Process 7 Lars Trieloff publish to online help
21. Slide 21: Activities in the Process 7 Lars Trieloff
22. 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
23. Slide 23: 9 The Toolchain Lars Trieloff We want a 100% free software toolchain to support roles and activities in the documentation process
24. 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)
25. Slide 25: Next: Tools for 11 Documentation Inkscape Lars Trieloff GIMP XML Editors? Emacs jEdit Lyx VIM Pollo Xerlin Quanta VEX
26. 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
27. 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)
28. 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
29. 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
30. 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