Effectively Managing Documentation  for Embedded Linux™ Projects Jeffrey Osier-Mixon
Who Am I <ul><li>Technical writer, project manager, developer </li></ul><ul><li>Open source experience </li></ul><ul><li>E...
Who Are You <ul><li>Technical writers and editors </li></ul><ul><li>Project managers for open-source projects </li></ul><u...
Goals of this Presentation <ul><li>The importance of solid documentation </li></ul><ul><li>The four critical elements of d...
The importance of solid documentation
What is documentation? <ul><li>“ What you tell other people about your project” </li></ul><ul><li>I emphasize  solid  rath...
What makes it solid? <ul><li>Primary education & training—concepts </li></ul><ul><li>Primary descriptions behavior and fea...
Who are the readers? <ul><li>Partners—product manufacturers or others who turn your project into a product to resell </li>...
The importance of solid documentation <ul><li>From a  partner’s  point of view, solid documentation: </li></ul><ul><li>Con...
The importance of solid documentation <ul><li>From the  developer’s  perspective, solid documentation: </li></ul><ul><li>C...
The importance of solid documentation <ul><li>From the  end user’s  point of view, solid documentation: </li></ul><ul><li>...
The importance of solid documentation <ul><li>From the  product’s  point of view, solid documentation: </li></ul><ul><li>A...
The importance of solid documentation <ul><li>From the  internal folks ’ point of view, good documentation: </li></ul><ul>...
The importance of solid documentation <ul><li>From an open-source point of view: </li></ul><ul><li>Collaboration and coope...
The four critical elements of documentation
Four Critical Elements <ul><li>In order by increasing level of detail: </li></ul><ul><li>Concepts </li></ul><ul><li>Tasks ...
Concepts <ul><li>The Big Picture:  35,000 foot high-resolution view </li></ul><ul><li>Describe the feature, construct, API...
Tasks <ul><li>Step by step examples: 5,000 foot view </li></ul><ul><li>Take common (and uncommon) tasks one at a time in a...
Reference <ul><li>Organized menu showing everything that’s available:  street view </li></ul><ul><li>Describe in as much d...
Troubleshooting <ul><li>Answering questions:  through the looking glass and looking back—the reader’s view </li></ul><ul><...
The Four-Element Theme <ul><li>Four-element  theme is  recursive: </li></ul><ul><li>Good example:  MontaVista’s  DevRocket...
Meeting expectations of readers
Meeting Reader’s Expectations <ul><li>Who are the readers </li></ul><ul><li>Partners—product manufacturers or others who t...
Meeting Reader’s Expectations <ul><li>What are their expectations? Interview? Survey? Educated guess?  </li></ul><ul><li>E...
Who are you, anyway? <ul><li>For this presentation: </li></ul><ul><ul><li>Technical writers and editors </li></ul></ul><ul...
And what do you want? <ul><li>Goals of this presentation </li></ul><ul><ul><li>The importance of solid documentation </li>...
The importance of effective  project management
Effective Project Management <ul><li>Documentation as a product is fundamentally different from software </li></ul><ul><ul...
Effective Project Management <ul><li>Establish resources </li></ul><ul><ul><li>Define and staff roles rather than jobs </l...
Questions for managers to ask <ul><li>Nature of the project: </li></ul><ul><li>Is this an open-source project, or a propri...
Questions for managers to ask <ul><li>Let the money be your guide, let the customer be your rudder: </li></ul><ul><li>Who ...
Questions for managers to ask <ul><li>Project management issues: </li></ul><ul><li>Home grow the docs with available resou...
Emerging Fashions
Emerging Fashions <ul><li>What kind of fashions? Why not “trends”? </li></ul><ul><ul><li>“ Trends” indicates business purp...
Emerging Fashions <ul><li>Political Direction </li></ul><ul><li>Content Delivery Mechanisms </li></ul><ul><li>Source Manag...
Political Direction—Toward Openness <ul><li>How does the open-source philosophy affect documentation, and CE products in g...
Content Delivery Mechanisms <ul><li>Open SDKs and developer portals  </li></ul><ul><ul><li>Blogs and RSS feeds </li></ul><...
Source Management <ul><li>Searchable HTML (printable PDF  is  so  early 2k) </li></ul><ul><li>Structured, open format—XML ...
Stylistic Trends <ul><li>Minimalism—counteracting the “dummies” trends and showing respect for the reader </li></ul><ul><l...
What about tools? <ul><li>Tools don’t matter, content is King </li></ul><ul><li>Easy to bog down believing one tool is sup...
What about tools? <ul><li>Tools matter a little bit, because timing is Queen </li></ul><ul><li>A known tool beats a new on...
Solid Documentation Matrix Internal KBs, searchable docs Public & private API docs Source code Internal examples Internal ...
Review: Goals of this Presentation <ul><li>The importance of solid documentation </li></ul><ul><li>The four critical eleme...
<ul><li>Jeffrey Osier-Mixon </li></ul><ul><li>707 326 3758 </li></ul><ul><li>[email_address] </li></ul><ul><li>http:// www...
Upcoming SlideShare
Loading in...5
×

Effectively Managing Documentation

484

Published on

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
484
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
22
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • Effectively Managing Documentation

    1. 1. Effectively Managing Documentation for Embedded Linux™ Projects Jeffrey Osier-Mixon
    2. 2. Who Am I <ul><li>Technical writer, project manager, developer </li></ul><ul><li>Open source experience </li></ul><ul><li>Embedded and bare-metal experience </li></ul><ul><li>Enterprise software experience </li></ul><ul><li>Consumer electronics experience </li></ul><ul><li>http://www.jefro.net </li></ul>
    3. 3. Who Are You <ul><li>Technical writers and editors </li></ul><ul><li>Project managers for open-source projects </li></ul><ul><li>Project managers for Linux-based proprietary products </li></ul><ul><li>Engineers stuck with writing tasks </li></ul><ul><li>Ten-year-old robotics enthusiasts </li></ul>
    4. 4. Goals of this Presentation <ul><li>The importance of solid documentation </li></ul><ul><li>The four critical elements of documentation </li></ul><ul><li>Meeting expectations of readers </li></ul><ul><li>The importance of effective project management </li></ul><ul><li>Emerging fashions </li></ul>
    5. 5. The importance of solid documentation
    6. 6. What is documentation? <ul><li>“ What you tell other people about your project” </li></ul><ul><li>I emphasize solid rather than good documentation: </li></ul><ul><ul><li>Complete and correct </li></ul></ul><ul><ul><li>Appropriate to audience </li></ul></ul><ul><ul><li>Answers the reader’s questions </li></ul></ul><ul><li>Spectrums of complexity, openness, and familiarity in presentation—always based on audience </li></ul>
    7. 7. What makes it solid? <ul><li>Primary education & training—concepts </li></ul><ul><li>Primary descriptions behavior and features—tasks </li></ul><ul><li>Primary definitive organized resource list—reference </li></ul><ul><li>Primary line of support—troubleshooting </li></ul><ul><li>(foreshadowing the four critical elements) </li></ul>
    8. 8. Who are the readers? <ul><li>Partners—product manufacturers or others who turn your project into a product to resell </li></ul><ul><li>Developers—organizations or people who use your project as basis for creating products of their own </li></ul><ul><li>End-users—people who finally use the end result of the above activities </li></ul><ul><li>Internal folks—people in your organization </li></ul>
    9. 9. The importance of solid documentation <ul><li>From a partner’s point of view, solid documentation: </li></ul><ul><li>Conveys intent as well as structure </li></ul><ul><li>Shows a clear product development path </li></ul><ul><li>Augments their own internal resources (engineering, QA, FAE, marketing, sales) </li></ul><ul><li>Makes their jobs easier: </li></ul><ul><ul><li>faster time to market </li></ul></ul><ul><ul><li>lower costs </li></ul></ul><ul><ul><li>higher satisfaction with provider </li></ul></ul><ul><li>Provides a format for change requests </li></ul>
    10. 10. The importance of solid documentation <ul><li>From the developer’s perspective, solid documentation: </li></ul><ul><li>Cements relationship with the provider </li></ul><ul><ul><li>Establishes professionalism </li></ul></ul><ul><ul><li>Reduces fear, uncertainty, and doubt </li></ul></ul><ul><li>Augments their own internal resources (engineering, QA, FAE, marketing, sales) </li></ul><ul><li>Makes their jobs easier: </li></ul><ul><ul><li>faster time to market </li></ul></ul><ul><ul><li>lower costs </li></ul></ul><ul><ul><li>higher satisfaction with provider </li></ul></ul><ul><li>Reduces support costs </li></ul>
    11. 11. The importance of solid documentation <ul><li>From the end user’s point of view, solid documentation: </li></ul><ul><li>Educates and involves the reader </li></ul><ul><li>Shows the product’s features in clear detail—if this can’t be easily done, the product itself is too complex </li></ul><ul><li>Provides a detailed, organized reference so that all details of the product can be instantly found </li></ul><ul><li>Provides troubleshooting, the first line of support </li></ul>
    12. 12. The importance of solid documentation <ul><li>From the product’s point of view, solid documentation: </li></ul><ul><li>Adds value to the product </li></ul><ul><li>Provides a glimmer of hope that education may prevail before trial-and-error sets in </li></ul><ul><li>Is the essential element to convert a bench project into a customer product –a process called productization </li></ul><ul><li>Doesn’t allow cleverness go unnoticed </li></ul><ul><ul><li>Describe and explain the product in ever finer detail, otherwise… </li></ul></ul><ul><ul><li>Useful features can go unnoticed in favor of the default behavior </li></ul></ul>
    13. 13. The importance of solid documentation <ul><li>From the internal folks ’ point of view, good documentation: </li></ul><ul><li>Provides a resource for the entire customer relationship: </li></ul><ul><ul><li>Marketing </li></ul></ul><ul><ul><li>Pre-sales </li></ul></ul><ul><ul><li>Professional services </li></ul></ul><ul><ul><li>Support </li></ul></ul><ul><ul><li>Retention </li></ul></ul><ul><li>Provides a basis for internal training </li></ul><ul><li>Provides a valuable record </li></ul>
    14. 14. The importance of solid documentation <ul><li>From an open-source point of view: </li></ul><ul><li>Collaboration and cooperation are key to success </li></ul><ul><li>Collaboration is made possible by communication </li></ul><ul><li>From a consumer electronics point of view: </li></ul><ul><li>A product can not be considered “marketable” without documentation describing it completely and correctly </li></ul>
    15. 15. The four critical elements of documentation
    16. 16. Four Critical Elements <ul><li>In order by increasing level of detail: </li></ul><ul><li>Concepts </li></ul><ul><li>Tasks & Examples </li></ul><ul><li>Reference </li></ul><ul><li>Troubleshooting </li></ul>
    17. 17. Concepts <ul><li>The Big Picture: 35,000 foot high-resolution view </li></ul><ul><li>Describe the feature, construct, API, entire platform, etc. with the reader in mind </li></ul><ul><li>Keep cross-references to a minimum </li></ul><ul><li>“ Tell” rather than “show” </li></ul><ul><li>Keep tone professional, not conversational </li></ul>
    18. 18. Tasks <ul><li>Step by step examples: 5,000 foot view </li></ul><ul><li>Take common (and uncommon) tasks one at a time in a logical order, with running examples </li></ul><ul><li>“ Show” rather than “tell” </li></ul><ul><li>Feed on previous tasks and examples, but try to make each one self-contained </li></ul><ul><li>Consistency is key </li></ul><ul><li>Keep cross-references to a minimum </li></ul>
    19. 19. Reference <ul><li>Organized menu showing everything that’s available: street view </li></ul><ul><li>Describe in as much detail as is appropriate </li></ul><ul><li>Leave no stone unturned </li></ul><ul><li>Refer back to previous sections for conceptual descriptions and examples </li></ul><ul><li>Keep cross-references to a maximum </li></ul>
    20. 20. Troubleshooting <ul><li>Answering questions: through the looking glass and looking back—the reader’s view </li></ul><ul><li>Probably the most important and most-read section, and least often included </li></ul><ul><li>Content is King, but understanding the reader is the Prime Minister </li></ul><ul><li>Display a sympathy for the reader and a willingness to show and teach—to be an advocate for the reader </li></ul>
    21. 21. The Four-Element Theme <ul><li>Four-element theme is recursive: </li></ul><ul><li>Good example: MontaVista’s DevRocket doc set </li></ul>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
    22. 22. Meeting expectations of readers
    23. 23. Meeting Reader’s Expectations <ul><li>Who are the readers </li></ul><ul><li>Partners—product manufacturers or others who turn your project into a product to resell </li></ul><ul><li>Developers—organizations or people who use your project as basis for creating products of their own </li></ul><ul><li>End-users—people who finally use the end result of the above activities </li></ul><ul><li>Internal—people in your organization </li></ul>
    24. 24. Meeting Reader’s Expectations <ul><li>What are their expectations? Interview? Survey? Educated guess? </li></ul><ul><li>Educate yourself with research—become the reader </li></ul><ul><li>Find out what they need to know conceptually </li></ul><ul><li>Find out what tasks they need to accomplish and make sure they are adequately described in your document </li></ul><ul><li>Find out where they can look for more information </li></ul>
    25. 25. Who are you, anyway? <ul><li>For this presentation: </li></ul><ul><ul><li>Technical writers and editors </li></ul></ul><ul><ul><li>Project managers </li></ul></ul><ul><ul><li>Engineers stuck with writing tasks </li></ul></ul><ul><li>Whom have I missed? </li></ul>
    26. 26. And what do you want? <ul><li>Goals of this presentation </li></ul><ul><ul><li>The importance of solid documentation </li></ul></ul><ul><ul><li>The four critical elements of documentation </li></ul></ul><ul><ul><li>Meeting expectations of readers </li></ul></ul><ul><ul><li>The importance of effective project management </li></ul></ul><ul><ul><li>Emerging fashions </li></ul></ul><ul><li>What do you want to know that we haven’t covered here? </li></ul>
    27. 27. The importance of effective project management
    28. 28. Effective Project Management <ul><li>Documentation as a product is fundamentally different from software </li></ul><ul><ul><li>Didactic rather than declarative </li></ul></ul><ul><li>Documentation project management is fundamentally similar to software project management </li></ul><ul><ul><li>Development, production, testing, deployment </li></ul></ul><ul><li>Documentation is fundamentally cross-functional </li></ul>
    29. 29. Effective Project Management <ul><li>Establish resources </li></ul><ul><ul><li>Define and staff roles rather than jobs </li></ul></ul><ul><ul><li>Identify tools, SMEs, access to information </li></ul></ul><ul><li>Plan: begin with the end in mind </li></ul><ul><ul><li>Get everyone’s input: marketing, sales, support, engineering, professional services, potential end users </li></ul></ul><ul><li>Aim for synergy with partners, developers, end users </li></ul><ul><li>Follow up, but don’t hover </li></ul>
    30. 30. Questions for managers to ask <ul><li>Nature of the project: </li></ul><ul><li>Is this an open-source project, or a proprietary project built on open-source components and/or tools </li></ul><ul><li>Hardware, software, or device containing both? </li></ul><ul><li>Where and for whom does this project add value? </li></ul>
    31. 31. Questions for managers to ask <ul><li>Let the money be your guide, let the customer be your rudder: </li></ul><ul><li>Who is the customer base? Partners, developers, end-users? </li></ul><ul><li>In which market niche? How does the market set expectations? </li></ul><ul><li>Who is the expected audience? Are they different from the customer base? </li></ul>
    32. 32. Questions for managers to ask <ul><li>Project management issues: </li></ul><ul><li>Home grow the docs with available resources, or seek professional writers? </li></ul><ul><li>If home grown, how to minimize costs and development downtime while maximizing quality? </li></ul><ul><li>If professional, contract or hire? </li></ul>
    33. 33. Emerging Fashions
    34. 34. Emerging Fashions <ul><li>What kind of fashions? Why not “trends”? </li></ul><ul><ul><li>“ Trends” indicates business purpose </li></ul></ul><ul><li>But you just told me to ignore fashions, didn’t you? </li></ul><ul><li>Many come from open source community </li></ul><ul><li>How to use fashions effectively in open-source: </li></ul><ul><ul><li>Emphasize developer participation & cooperation rather than secrecy and direct competition </li></ul></ul><ul><ul><li>Follow fashions that increase value, ignore others </li></ul></ul><ul><ul><li>Remember that content is King </li></ul></ul>
    35. 35. Emerging Fashions <ul><li>Political Direction </li></ul><ul><li>Content Delivery Mechanisms </li></ul><ul><li>Source Management </li></ul><ul><li>Stylistic Trends </li></ul><ul><li>Tools </li></ul>
    36. 36. Political Direction—Toward Openness <ul><li>How does the open-source philosophy affect documentation, and CE products in general? </li></ul><ul><li>Openness </li></ul><ul><li>Collaboration </li></ul><ul><li>Cooperation </li></ul><ul><li>Very confusing for historically proprietary markets such as consumer electronics & telecommunications </li></ul>
    37. 37. Content Delivery Mechanisms <ul><li>Open SDKs and developer portals </li></ul><ul><ul><li>Blogs and RSS feeds </li></ul></ul><ul><ul><li>Developer forums </li></ul></ul><ul><ul><li>FAQ and Knowledge Base </li></ul></ul><ul><li>Wikis and public bug tracking systems </li></ul><ul><ul><li>Public participation </li></ul></ul><ul><ul><li>Direct feedback to developers and end-users </li></ul></ul><ul><li>White papers, articles, technical specifications </li></ul>
    38. 38. Source Management <ul><li>Searchable HTML (printable PDF is so early 2k) </li></ul><ul><li>Structured, open format—XML in its many forms </li></ul><ul><li>Source-generated docs (doxygen, javadoc) </li></ul><ul><li>Content management systems </li></ul><ul><li>Bug tracking </li></ul>
    39. 39. Stylistic Trends <ul><li>Minimalism—counteracting the “dummies” trends and showing respect for the reader </li></ul><ul><li>Conversational tone vs professional tone, both in vogue in different contexts </li></ul><ul><li>Writing for non-native English speakers, writing for translation and localization </li></ul><ul><li>Pictures—images, line drawings, screenshots, etc. can convey meaning beyond translation </li></ul>
    40. 40. What about tools? <ul><li>Tools don’t matter, content is King </li></ul><ul><li>Easy to bog down believing one tool is superior </li></ul><ul><li>Any document can be written with any decent set of writing tools. Pick a good one and get going </li></ul><ul><li>Avoid “tool fashion” at all costs </li></ul><ul><li>Saving money on tools is no more effective in software development than it is in house construction </li></ul>
    41. 41. What about tools? <ul><li>Tools matter a little bit, because timing is Queen </li></ul><ul><li>A known tool beats a new one when time is short </li></ul><ul><li>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 </li></ul><ul><li>Using proprietary tools in an open-source project can sometimes lead to problems down the road </li></ul><ul><li>If a tool makes the job harder, uglier, longer, or less future-proof, replace it </li></ul>
    42. 42. 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
    43. 43. Review: Goals of this Presentation <ul><li>The importance of solid documentation </li></ul><ul><li>The four critical elements of documentation </li></ul><ul><li>Meeting expectations of readers </li></ul><ul><li>The importance of effective project management </li></ul><ul><li>Emerging fashions </li></ul><ul><li>How did we do? </li></ul>
    44. 44. <ul><li>Jeffrey Osier-Mixon </li></ul><ul><li>707 326 3758 </li></ul><ul><li>[email_address] </li></ul><ul><li>http:// www.jefro.net </li></ul>
    1. Gostou de algum slide específico?

      Recortar slides é uma maneira fácil de colecionar informações para acessar mais tarde.

    ×