Effectively Managing Documentation for Embedded Linux Projects Jeffrey

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 reader’s questions • Spectrums of complexity, openness, and familiarity in presentation—always based on audience

What makes it solid? • Primary education & training—concepts • Primary descriptions behavior and features—tasks • Primary definitive organized resource list— reference • Primary line of support—troubleshooting (foreshadowing the four critical elements)

Who are the readers? • Partners—product manufacturers or others who turn your project into a product to resell • Developers—organizations or people who use your project as basis for creating products of their own • End-users—people who finally use the end result of the above activities • Internal folks—people in your organization

The importance of solid documentation From a partner’s 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 developer’s 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 user’s point of view, solid documentation: • Educates and involves the reader • Shows the product’s features in clear detail—if this can’t 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 product’s 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 product–a process called productization • Doesn’t allow cleverness go unnoticed – Describe and explain the product in ever finer detail, otherwise… – Useful features can go unnoticed in favor of the default

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

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 that’s 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 back—the reader’s 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 teach—to be an advocate for the reader

The Four-Element Theme Four-element theme is recursive: Good example: Monta. Vista’s Dev. Rocket doc set Concepts Tasks & Examples Reference Troubleshooting Doc set in general Overview & Specs Prog. Guides Tutorials API Guides FAQs Glob. Index KBs Search func. Each document Prefatory chapters “How-To” chapters Appendices Optional trouble. Index shooting sec. Each chapter Overview Task and example sections Cross-refs to reference to related documents information Each individual element Introduce topic, task, example Step by step instructions Cross-refs to reference to related documents information

Meeting expectations of readers

Meeting Reader’s Expectations Who are the readers • Partners—product manufacturers or others who turn your project into a product to resell • Developers—organizations or people who use your project as basis for creating products of their own • End-users—people who finally use the end result of the above activities • Internal—people in your organization

Meeting Reader’s Expectations What are their expectations? Interview? Survey? Educated guess? • Educate yourself with research—become 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 haven’t 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 crossfunctional

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 everyone’s input: marketing, sales, support, engineering, professional services, potential end users • Aim for synergy with partners, developers, end users • Follow up, but don’t 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?

Emerging Fashions

Emerging Fashions • What kind of fashions? Why not “trends”? – “Trends” indicates business purpose • But you just told me to ignore fashions, didn’t you? • Many come from open source community • How to use fashions effectively in opensource: – 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 Direction—Toward 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 2 k) • Structured, open format—XML in its many forms • Source-generated docs (doxygen, javadoc) • Content management systems • Bug tracking

Stylistic Trends • Minimalism—counteracting 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 • Pictures—images, line drawings, screenshots, etc. can convey meaning beyond translation

What about tools? Tools don’t 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 project’s 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

Solid Documentation Matrix Concepts Tasks & Reference Trouble. Examples shooting Partners Specifications Low-level guides Good samples Private API documents Source code Develope rs End. Users Internal Folks Conceptual overviews Programming guides, good samples Public API Blogs, forums, documents on a white papers public portal White papers Training Step-by-step instructions with pictures Good indices FAQs, Searchable docs Knowledge Bases Internal wikis Internal training examples Public & private API docs Source code Shared wikis, white papers 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?

Jeffrey Osier-Mixon 707 326 3758 jefro@jefro. net http: //www. jefro. net