Effectively Managing Documentation for Embedded Linux Projects Jeffrey Osier-Mixon
Who Am I Technical writer, project manager, developer Open source experience Embedded and bare-metal experience Enterprise software experience Consumer electronics experience http://www.jefro.net
Who Are You Technical writers and editors Project managers for open-source projects Project managers for Linux-based proprietary products Engineers stuck with writing tasks Ten-year-old robotics enthusiasts
Goals of this Presentation The importance of solid documentation The four critical elements of documentation Meeting expectations of readers The importance of effective project management Emerging fashions
The importance of solid documentation
What is documentation? What you tell other people about your project I emphasize solid rather than good documentation: Complete and correct Appropriate to audience Answers the readers questions Spectrums of complexity, openness, and familiarity in presentationalways based on audience
What makes it solid? Primary education & trainingconcepts Primary descriptions behavior and featurestasks Primary definitive organized resource listreference Primary line of supporttroubleshooting (foreshadowing the four critical elements)
Who are the readers? Partnersproduct manufacturers or others who turn your project into a product to resell Developersorganizations or people who use your project as basis for creating products of their own End-userspeople who finally use the end result of the above activities Internal folkspeople in your organization
The importance of solid documentation From a partners point of view, solid documentation: Conveys intent as well as structure Shows a clear product development path Augments their own internal resources (engineering, QA, FAE, marketing, sales) Makes their jobs easier: faster time to market lower costs higher satisfaction with provider Provides a format for change requests
The importance of solid documentation From the developers perspective, solid documentation: Cements relationship with the provider Establishes professionalism Reduces fear, uncertainty, and doubt Augments their own internal resources (engineering, QA, FAE, marketing, sales) Makes their jobs easier: faster time to market lower costs higher satisfaction with provider Reduces support costs
The importance of solid documentation From the end users point of view, solid documentation: Educates and involves the reader Shows the products features in clear detailif this cant be easily done, the product itself is too complex Provides a detailed, organized reference so that all details of the product can be instantly found Provides troubleshooting, the first line of support
The importance of solid documentation From the products point of view, solid documentation: Adds value to the product Provides a glimmer of hope that education may prevail before trial-and-error sets in Is the essential element to convert a bench project into a customer producta process called productization Doesnt allow cleverness go unnoticed Describe and explain the product in ever finer detail, otherwise Useful features can go unnoticed in favor of the default behavior
The importance of solid documentation From the internal folks point of view, good documentation: Provides a resource for the entire customer relationship: Marketing Pre-sales Professional services Support Retention Provides a basis for internal training Provides a valuable record
The importance of solid documentation From an open-source point of view: Collaboration and cooperation are key to success Collaboration is made possible by communication From a consumer electronics point of view: A product can not be considered marketable without documentation describing it completely and correctly
The four critical elements of documentation
Four Critical Elements In order by increasing level of detail: Concepts Tasks & Examples Reference Troubleshooting
Concepts The Big Picture: 35,000 foot high-resolution view Describe the feature, construct, API, entire platform, etc. with the reader in mind Keep cross-references to a minimum Tell rather than show Keep tone professional, not conversational
Tasks Step by step examples: 5,000 foot view Take common (and uncommon) tasks one at a time in a logical order, with running examples Show rather than tell Feed on previous tasks and examples, but try to make each one self-contained Consistency is key Keep cross-references to a minimum
Reference Organized menu showing everything thats available: street view Describe in as much detail as is appropriate Leave no stone unturned Refer back to previous sections for conceptual descriptions and examples Keep cross-references to a maximum
Troubleshooting Answering questions: through the looking glass and looking backthe readers view Probably the most important and most-read section, and least often included Content is King, but understanding the reader is the Prime Minister Display a sympathy for the reader and a willingness to show and teachto be an advocate for the reader
The Four-Element Theme Four-element theme is recursive: Good example: MontaVistas DevRocket doc set ConceptsTasks & Examples ReferenceTrouble- shooting Doc set in general Overview & Specs Prog. Guides Tutorials API Guides Glob. Index Search func. FAQs KBs Each document Prefatory chapters How-To chapters Appendices Index Optional trouble- shooting sec. Each chapterOverviewTask and example sections Cross-refs to reference documents Cross-refs to related information Each individual element Introduce topic, task, example Step by step instructions Cross-refs to reference documents Cross-refs to related information
Meeting expectations of readers
Meeting Readers Expectations Who are the readers Partnersproduct manufacturers or others who turn your project into a product to resell Developersorganizations or people who use your project as basis for creating products of their own End-userspeople who finally use the end result of the above activities Internalpeople in your organization
Meeting Readers Expectations What are their expectations? Interview? Survey? Educated guess? Educate yourself with researchbecome the reader Find out what they need to know conceptually Find out what tasks they need to accomplish and make sure they are adequately described in your document Find out where they can look for more information
Who are you, anyway? For this presentation: Technical writers and editors Project managers Engineers stuck with writing tasks Whom have I missed?
And what do you want? Goals of this presentation The importance of solid documentation The four critical elements of documentation Meeting expectations of readers The importance of effective project management Emerging fashions What do you want to know that we havent covered here?
The importance of effective project management
Effective Project Management Documentation as a product is fundamentally different from software Didactic rather than declarative Documentation project management is fundamentally similar to software project management Development, production, testing, deployment Documentation is fundamentally cross-functional
Effective Project Management Establish resources Define and staff roles rather than jobs Identify tools, SMEs, access to information Plan: begin with the end in mind Get everyones input: marketing, sales, support, engineering, professional services, potential end users Aim for synergy with partners, developers, end users Follow up, but dont hover
Questions for managers to ask Nature of the project: Is this an open-source project, or a proprietary project built on open-source components and/or tools Hardware, software, or device containing both? Where and for whom does this project add value?
Questions for managers to ask Let the money be your guide, let the customer be your rudder: Who is the customer base? Partners, developers, end-users? In which market niche? How does the market set expectations? Who is the expected audience? Are they different from the customer base?
Questions for managers to ask Project management issues: Home grow the docs with available resources, or seek professional writers? If home grown, how to minimize costs and development downtime while maximizing quality? If professional, contract or hire?
What kind of fashions? Why not trends? Trends indicates business purpose But you just told me to ignore fashions, didnt you? Many come from open source community How to use fashions effectively in open-source: Emphasize developer participation & cooperation rather than secrecy and direct competition Follow fashions that increase value, ignore others Remember that content is King
Emerging Fashions Political Direction Content Delivery Mechanisms Source Management Stylistic Trends Tools
Political DirectionToward Openness How does the open-source philosophy affect documentation, and CE products in general? Openness Collaboration Cooperation Very confusing for historically proprietary markets such as consumer electronics & telecommunications
Content Delivery Mechanisms Open SDKs and developer portals Blogs and RSS feeds Developer forums FAQ and Knowledge Base Wikis and public bug tracking systems Public participation Direct feedback to developers and end-users White papers, articles, technical specifications
Source Management Searchable HTML (printable PDF is so early 2k) Structured, open formatXML in its many forms Source-generated docs (doxygen, javadoc) Content management systems Bug tracking
Stylistic Trends Minimalismcounteracting the dummies trends and showing respect for the reader Conversational tone vs professional tone, both in vogue in different contexts Writing for non-native English speakers, writing for translation and localization Picturesimages, line drawings, screenshots, etc. can convey meaning beyond translation
What about tools? Tools dont matter, content is King Easy to bog down believing one tool is superior Any document can be written with any decent set of writing tools. Pick a good one and get going Avoid tool fashion at all costs Saving money on tools is no more effective in software development than it is in house construction
What about tools? Tools matter a little bit, because timing is Queen A known tool beats a new one when time is short Writing tools should be a very small percentage of the projects budget, but time and labor can be a very large percentage with the wrong tools Using proprietary tools in an open-source project can sometimes lead to problems down the road If a tool makes the job harder, uglier, longer, or less future-proof, replace it
Solid Documentation Matrix ConceptsTasks & Examples ReferenceTrouble- shooting Partners SpecificationsLow-level guides Good samples Private API documents Source code Shared wikis, white papers Developers Conceptual overviews Programming guides, good samples Public API documents on a public portal Blogs, forums, white papers End-Users White papers Training Step-by-step instructions with pictures Good indices Searchable docs FAQs, Knowledge Bases Internal Folks Internal wikis Internal training Internal examplesPublic & private API docs Source code Internal KBs, searchable docs
Review: Goals of this Presentation The importance of solid documentation The four critical elements of documentation Meeting expectations of readers The importance of effective project management Emerging fashions How did we do?