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

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

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

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 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)

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

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

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

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

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 behavior

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 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

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

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

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

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

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

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

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: MontaVista’s DevRocket doc set Cross-refs to related information Cross-refs to reference documents Step by step instructions Introduce topic, task, example Each individual element Cross-refs to related information Cross-refs to reference documents Task and example sections Overview Each chapter Optional trouble-shooting sec. Appendices Index “ How-To” chapters Prefatory chapters Each document FAQs KBs API Guides Glob. Index Search func. Prog. Guides Tutorials Overview & Specs Doc set in general Trouble-shooting Reference Tasks & Examples Concepts

Four-element theme is recursive:

Good example: MontaVista’s DevRocket doc set

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

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

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?

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?

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 cross-functional

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 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

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?

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?

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?

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 open-source: Emphasize developer participation & cooperation rather than secrecy and direct competition Follow fashions that increase value, ignore others Remember that content is King

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 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 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

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

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 format—XML in its many forms Source-generated docs (doxygen, javadoc) Content management systems Bug tracking

Searchable HTML (printable PDF is so early 2k)

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

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

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 less future-proof, replace it

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 less future-proof, replace it

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

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?

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 [email_address] http:// www.jefro.net

Jeffrey Osier-Mixon

707 326 3758

[email_address]

http:// www.jefro.net