Supporting Technical Documentation Processes with Open Source Tools. A presentation by Lars Trieloff held on Linux Tag 2007 in Berlin.
1.1Lars Trieloff Open Source forTech Writing Teams Supporting Technical Documentation with OpenSource Tools
2. About the Speaker2 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. Introduction3High tech vendors need technical Lars Trieloffdocumentation Open Source projects need technical documentation even moreMediator between the product andthe usertechnical documentation needs: people process toolsThis talk is all about process&tools 4. Processes: Who needs 4them? help us coordinate teamwork Lars Trieloff help us coordinate people help us coordinate tasks help us coordinate knowledgeConclusion: We need processes 5. How information 5workers work Lars Trieloff 6. Who collaborates in technical documentation 6Lars Trieloff 7. Activities in the Process 7 Lars Trieloff 8. Activities in the Process 7 Lars Trielofflearn aboutthe user 9. Activities in the Process 7 Lars Trielofflearn aboutthe product 10. Activities in the Process 7 Lars Trieloffevaluatecurrent docs 11. Activities in the Process 7 Lars Trieloffsynthesize information 12. Activities in the Process 7 Lars Trieloffwrite theinformationplan 13. Activities in the Process 7 Lars Trieloffcreate the content specication 14. Activities in the Process 7 Lars Trieloff create the rst draft 15. Activities in the Process 7 Lars Trieloffreview the rst draft 16. Activities in the Process 7 Lars Trieloff write the second draft 17. Activities in the Process7Lars Trieloff copy-editing 18. Activities in the Process7Lars Trieloff localization & translation 19. Activities in the Process 7 Lars Trieloff publish to print and web 20. Activities in the Process 7 Lars Trieloff publish to online help 21. Activities in the Process 7 Lars Trieloff 22. Management Activities8 Development of a project planLars Trieloff Development of estimates for all activities Tracking of hours expended for all activitiescost-control, better estimates, better managebility Manage translators Manage production checklist 23. 9 The Toolchain Lars Trieloff We want a 100% free software toolchain to support roles and activities in the documentation process 24. The Basics: Documentation Format 10 DocBookLars Trieloffestablished open source documentation formatlots of toolsAlternatives: DITA, Tex Image Publishing:PNG (raster graphics) and SVG (vector graphics) 25. Next: Tools for 11 DocumentationInkscape Lars TrieloffGIMPXML Editors? Emacs jEdit Lyx VIM Pollo Xerlin Quanta VEX 26. Advanced: Team 12 InfrastructureTechnical Documentation can learn Lars Trielofffrom Software Development. Different Work Same Problems Similar Solutions Possible Three signs of successful softwareprojects: Version Control Systems Bug Tracking Systems Wikis 27. Version Control 13A safeguard for your work Lars Trieloff nothing gets lost undo/redo for your teamActivity tracking logs differential comparisonConcurrent work merging we are using XML, its possibleVersion Control Systems Subversion Bazaar, Mercurial, Codeville Mindquarry (easy to use GUI) 28. Bug Tracking14In software development: Lars TrieloffBug TrackingIssue TrackingIn technical documentation:task trackingBenetseveryone knows what to domanagers can trackallows bottom-up-managementState of the Art:Bugzilla (Powerful, but complex)Mindquarry is a lightweight tasktracker for teams 29. Wikis 15Where to use Lars Trieloff collaborative whiteboard collaborative outliner collaborative mindmap collaborative website gather information in wikisDo not use Wikis for producingcontents - Its authoring capabilitiesare weak compared to yourdesktop toolsSoftware MediaWiki, MoinMoin, Mindquarry 30. Conclusion 16 Technical Documentation is difcult 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