Documenting Open Source

Documenting Open Source
A Guide for Reaching Your Audience
Who am I?
Scott Meyers
Sr. Development Editor at Pearson Education
(Sams/Que/Developers Library…)
I work at shaping content to fit the needs of a
specific audience
Been doing it for over 8 years
[email protected]
[email protected]
What am I teaching?
Types of documentation
Styles of documentation
Considerations in reaching your target
audience
Break Down
Overview of Document Types, Styles,
and Audiences
Documentation Types
Integrated Documentation
Supplemental Documentation
Commercial Documentation
Integrated Documentation
Code Comments
Build Documents
Man / info pages
README’s
Integrated Help
Command Line Switches (-h -? --help)
OS Level Help Systems
Supplemental Documentation
FAQ’s
Online Doc’s
Support Web Sites
Online Forums
Others…
Commercial Documentation
‘Zine / Journal Articles
eBooks*
Safari
OSoft
Dead Tree Books
*Not all eBooks are commercial.
Documentation Styles
References
Dictionary (i.e. Function) References
Solution (i.e. Cookbook) References
Tutorials
Expositions
Other
Dictionary References
Often command of function references
Usually organized alphabetically (may be
subdivided by topic)
Great for experienced users needing a
refresher or pointer
Solution References
Organization varies by technology and
implementation
Ideal for providing solutions to specific real
world problems
Reference Writing Tips
A logical, easily understood organization is
necessary
Most references are geared for experienced
users* – it’s a bad idea to reach too low as it
frustrates your core audience
Even with dictionary style references, real
world examples are always desirable
* Some specific “task” references are geared towards new users – know your audience!
Tutorials
Generally designed to progress a reader
through a linear learning curve
Suited for people wish to learn a new
technology or a specific aspect of a
technology
Tutorial Writing Tips
Always attempt to show the reader what you
are teaching with examples (as opposed to
telling the reader)
Try to build upon previous lessons as the
document progresses
Avoid unnecessary informational exposition
Expository Writing
Good for providing high level information,
overview, or review
Almost always linear
Can often be opinionated, ideological, or
academic
Expository Writing Tips
Unless you are universally recognized as the
preeminent expert on your topic, you should
attempt to gather as many supplemental real
world facts as possible and site them liberally
Always back up a statement with the how’s
and why’s
Avoid overgeneralizations, labels and
buzzwords*
* Unless this is a marketing piece and that’s all you have
Other Writing Styles
Usually a combination of other styles
targeted for an audiences specific wants and
needs
The Audience!
Developers
Administrators
End Users
Power Users (all of the above)
Others
Why Focus on Audience?
Your audience should be the main factor in
determining documentation type and style
Without a clear idea of who you are writing
for, you can not consistently provide the
solutions your readers are looking for
Choosing Your Audience
Be as specific as possible given the practical
scope of your project
Try to think of your audience as real people
rather than abstract labels
Example: Audience Definition
“Software Developers and System Architects
building applications with X Application
Server.”
“Developers who are tasked with building
multi-tier applications, often involving data
from a variety of both legacy and modern
systems.”
A Premise…
All audiences turn to documentation for
solutions to problems
Determining Audience Needs
Personal Experience
Feedback
Are you writing for peers?
Are you writing as an authority or mentor?
How far removed from the learning curve are
you?
Developers Want…
To see how a technology can solve their
problems
To learn how to implement the technology
To apply the technology to their specific
purpose
To extend their knowledge of the technology
to extend their goals
Administrators Want
To be shown how a technology can be
integrated into an existing system
To assure a technology is stable and “safe”
for implementation
To see that a technology will be appropriate
for both current and future needs
End Users Want
To learn how to use a technology to complete
a specific task
To only learn what is necessary to complete
their task
To find specific solutions to common
problems that End Users encounter*
* End Users are rarely interested in proactive measures, that is until it’s too late
Power Users Want…
To utilize a technology to its maximum
capabilities
To extend a technology or combine it with
other technologies to create new, interesting
solutions
To occasionally understand how or why
something works
Documentation Examples
Looking at Various Document Types
and Styles
Code Comments
Creating useful code comments
Assumptions About Audience
Familiar with language (at least competent)
and adjacent technologies
Interested in extending or understanding
code
Probably a developer or aspiring developer
What Should Comments Tell
The Reader
Explain what the code does and who’s responsible
for it
Provide “signposts” for how the code is organized
Give pointers to external resources
Describe any “special” code.
“Hacks”
“Beta” code
…etc…
Comment Examples
mod_dav.c
mod_example.c
Recipe Project
Online Documentation
Creating Online Documentation
Keys to Great Online
Documentation
Great organization
Consistent navigation
Keep it up to date
Simple effective style (design)
Utilize the medium!*
* Wisely!
Assumptions about Audience
The reader is interested in some aspect of the
technology
Could be there for any number of reasons and could
represent any level of user
Many of websites (especially eJournals & blogs)
attract a “target audience”
In some cases the referrer to the site may have
vetted, and perhaps summarized, the information.
Expectations of Official
Website Documentation
News
Official FAQs
“Getting Started” Documentation
Reference Materials
Language
API’s
… etc …
Links to other relevant information sources
Documentation Goals: Official
Website
Evangelize
Document core features
Provide support*
Sell support or services*
Provide links to partners and additional
information*
* This depends on commercial aspirations
Examples: Official Web Sites
http://php.net/
http://httpd.apache.org/
http://www.mysql.com/
Types of “Unofficial” Online
Documentation
Technology Related Blogs
Developer blogs
Technology aggregators
Official “Partner” Website
Enthusiast and Community Websites
Commercial eJournals
eBooks
Assumptions about Audience
While it’s a very big assumption you may
assume…
Many of these websites (especially eJournals
& blogs) attract a “target audience”
The referrer to the site has vetted, and
perhaps summarized, the information
Examples: Online
Documentation
http://www.planet-php.net/ (blog – aggregator)
http://www.zend.com/ (partner)
http://www.faqts.com/knowledge_base/index.phtml
/fid/51/ (community)
http://www.phpbuilder.com/ (community eJournal)
http://www.onlamp.com/php/ (commercial
eJournal)
The Bookstore
Writing Books Comercially
The Dual Audience Sales
Conundrum in Book Publishing
It’s important to understand the sales chain to be
successful in writing commercial documentation
You are selling your title to different audiences
with different desires
The consumer who buys and reads your book
The bookstore, distributor, and even publisher who want
to make sure that your book is marketable
The Consumer…
… is usually searching for commercial
documentation out of some informational
need (not too many impulse buys)
… wants to be assured that their needs will
be met before their purchase
There are very few topics where the
consumer does not have choices
The Book Sellers…
… only buy books that they think will sell*
… are more likely to buy into a technology or series
with a proven track record of success
… are fairly adverse to risk
… also almost always have choices in any given
topic
… may be reactionary, but are pretty good at
responding to consumer demands
* And given the fact that they are not all that techno-savvy, they are pretty good at knowing the market
The Publisher…
… wants to work with the author to meet the
requirements of both the book seller and the
consumer
… sells to the book seller not the consumer*
… must balance publishing overhead with
perceived value of published work
… is always interested in creating situations where
choice is limited
* Though that is beginning to change
Keys to Book Writing
Before you can sell you document to the consumer, you first
must sell the idea to a publisher*
The more useful your book is in solving the consumer’s
need, the more likely the consumer will choose your book
over someone else's
For commercial success, you want to balance being as
focused as possible for the largest possible audience**
Audience may be generally pre-defined for certain series
and publishers
*Unless you are self publishing
** “making the net as big as possible without letting the fish escape” rule
Commercial Documentation
Examples
Book: http://safari.informit.com/
eBook: http://www.tidbits.com/
eBook: Osoft ThoutReader
(http://www.osoft.com/)
Magazines
Questions?
Q&A Time