Effectively Managing Documentation for Embedded Linux Projects

1
Effectively Managing Documentation for Embedded
Linux Projects
Jeffrey Osier-Mixon
2
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

3
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

4
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

5
The importance of solid documentation
6
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

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

8
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

9
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

10
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

11
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

12
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 to go unnoticed
• Describe and explain the product in ever finer
  detail, otherwise
• Useful features can go unnoticed in favor of the
  default behavior

13
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

14
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

15
The four critical elements of documentation
16
Four Critical Elements

• In order by increasing level of detail
• Concepts
• Tasks Examples
• Reference
• Troubleshooting

17
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

18
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

19
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

20
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

21
The Four-Element Theme

• Four-element theme is recursive
• Good example MontaVistas DevRocket doc set

22
Meeting expectations of readers
23
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

24
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

25
Who are you, anyway?

• For this presentation
• Technical writers and editors
• Project managers
• Engineers stuck with writing tasks
• Whom have I missed?

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

27
The importance of effective project management
28
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

29
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

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

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

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

33
Emerging Fashions
34
Emerging Fashions

• 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

35
Emerging Fashions

• Political Direction
• Content Delivery Mechanisms
• Source Management
• Stylistic Trends
• Tools

36
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

37
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

38
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

39
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

40
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

41
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

42
Solid Documentation Matrix
43
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?

44

• Jeffrey Osier-Mixon
• 707 326 3758
• jefro_at_jefro.net
• http//www.jefro.net