Documentation and publishing

Docs and
publishing
McrFred Sep ’13 // Chris Mills, Mozilla
Monday, 23 September 13

WhoamI? Senior tech writer @
Formerly tech writer & evangelist @
HTML, CSS, JS and Mobile enthusiast
Accessibility whingebag
Education agitator
Heavy metal geek dad

Contact
slideshare.net/chrisdavidmills
cmills@mozilla.com
@chrisdavidmills

backgrd Mozilla since July 2013
Opera 2007-2013
Apress/friends of ED 2003-2007
Wrox/glasshaus 2000-2003

backgrd Simon asked me to speak at McrFred
Over a beer or 4
I’m setting out to answer a question

Is documentation really
boring?

Traditional publishing

tradpub Traditional publishing has been around
for 100s of years
Well-established brands like Pearson,
Springer, Oxford University Press

tradpub Subject matter expert provides
knowledge
Publisher provides word craft, guidance,
marketing, distribution, layout,
production, etc.

tradpub Author gets advance + royalties
Advance has to be earnt out before any
more royalties are earnt
Revenue also comes in through e-
books, translations, etc.

tradpub You won’t make money by writing books
Writing a book takes 6 months, and
you’ll earn about 4-10K
You might get lucky

tradpub Popular area (HTML/CSS?)
Niche area that you own
You have personal marketing ability (big
name, lots of mates)
Also great for your personal brand

gotchas You have to watch out for international
tax (e.g. you need an ITIN when
working with US companies)
Many publishers don’t actually do that
much promotion

gotchas Careful of product quality and ethics
Many publishers check the spelling,
then pour your content into an ugly
template
Book series, formulaic cover...does this
fit your book’s style?

also... A print run is about 3-6000 copies
A huge waste...
...if it contains serious mistakes
...and/or doesn’t sell

gotchas Contract bullshit: non-compete
clauses
Liability for project completion
When is the advance paid?
Some publishers sign a bunch of
projects, knowing they will can some
of the less promising ones

thisiswhy This is why publishers like Five Simple
Steps and A Book Apart started to
appear
Books by designers, for designers

trouble
The main trouble is that trad publishing
is no good for fast moving topics like
open standards, even with eBooks, and
new editions... it is too slow

Changing languages
Changing APIs, libraries
Changing standards
Changing browser support
Changing best practices
Aaargh!

trouble
And licensing of traditional publishers
tends to be incompatible with open
licensing.

self Self publishing solves many problems
Publish as eBook
Print on demand, so no warehouse
stock
And you can update the copy when
necessary

self Do your own production
Or get someone else to do it
Use a service like Lulu, CreateSpace,
iUniverse, Xlibris...

self You could buy your own ISBN and set
up your own publishing house
You’ll need to print it yourself, create
a cover, get it copy edited, etc.
POD printers like LightningSource...

self Marketing/distribution is the issue
You need to get it on amazon, B&N,
iTunes, and other main outlets
This is really just legwork

self Marketing requires some guerrilla action
Set up a site with referral links to buy
Keep promoting it ruthlessly
Keep publishing related articles, do
talks, give tidbits away for free
Turn the whole promotion effort into a
product

snook! SMACSS.com is a great case in point

piracy ...piracy has never worried me
It actually tends to help
Pirates wouldn’t buy it anyway
It can help get the word out
Some will always want a proper book

Online publishing

online
Blogs
Wikis
Packaged/integrated docs

ingeneral Can publish instantly
Can fix instantly
More iterative
Instant wide distribution

blogs Of the moment information
Great for promotion
Great for individual articles
Quick to dream up and publish

blogs
Not as immediately collaborative
Not as good for structured docs
Less browsable

although
Blogs can turn into books
Or even publishing companies
This is how Five Simple Steps started

cases A List Apart
Smashing Mag
dev.opera.com
Mozilla Hacks

wikis
Great for collaboration
Great for structuring content
Great for building communities

wikis Lots more thought needed
Content quickly becomes a mess
Curation needed
Community building needs love and
attention
Spamming not necessarily that big a
problem

wikis Wikis do have a stigma
People assume crowd sourced means
low quality and ugly
But you can change that
It’s all about perception

cases Wikipedia ;-)
MDN!!
My little pony Wiki, apparently
Any good computer game ever...
Many are really bad

Packaged/integrated

packaged Why not package docs along with your
product?
Or generate them from the product?
Great for offline use
Always at hand

packaged Need to update docs as you update
distribution
Some systems require building, so make
sure you are clear on instructions
Developers are not necessarily the best
doc writers

packaged Jekyll (jekyllrb.com/)
Apiary (apiary.io/)
JSDoc (github.com/jsdoc3/jsdoc)
Readthedocs
Sphinx
HTML!

packaged A packaged doc format doesn’t allow
collaboration as easily
Although you could allow external
contributions via github

What’s for the best?

hybrid Why not do all three?
feed the same docs into both the
online and offline doc versions
Allow external contributions
Do regular blog posts to highlight
product features or new content

cases Wiki, API to feed packaged docs?
Something like jekyll, hosted on github.
Use that to feed the online version,
then clone for offline use

Communities

commune Community building is hard
But rewarding
You can get a huge amount of input
But you need to keep nurturing them

commune
A community needs a clear purpose
Reason to come back
Rewards

commune
Mozilla
Linux/Ubuntu
Opera

reasons Fight the power
Collaborate on some work
Achieve a good cause
Common interest

rewards Badges (gamification)
Contributor of the week
Schwag
Flights to events
Socialisation (being right)

focii Easy communication (IRC, mailing list)
But not too much
Weekly meetings
Doc Sprints

contrib Contributions need some kind of login
To cut down on spam
And make contributions recordable
(blame & reward)
But make it as easy
as possible

contrib Edit wars less of a problem than you’d
think
If it gets really bad, you might
have to ban users
temporarily

Feedback

feedback
Is vital
Is hard to get right
Is a pain in the ass

feedback Provide as many feedback mechanisms
as you need
But as few as possible
Each one carries extra overhead

feedback Comments (in page?)
Forums (linked to articles?)
Wiki talk pages
IRC/mailing lists

feedback Feedback needs to be accessible
Without being too intrusive
How do you get the feedback you
want?
Curation can be a massive time-sink

feedback It needs to work with your workflow
I like to get everything in my inbox
If it’s sat on a forum or bugzilla, then
I won’t check it

Content

content What constitutes good content?
Content that teaches the target
audience what they need to know as
quickly as possible, and which is
findable.

content Focus on a solid atomic subject in
each article.
Not the kitchen sink
And make it meaningful, not “167 best
Web RTC demos”

content If it’s a guide or a tutorial, tell a
story
Build up towards a crescendo, and
ultimate purpose
Make the goal and journey clear at the
start

content
Rambling directionless narratives are
awful

content Get your target audience right
Decide what your assumptions are
Think about what style suits them
best

content Make your article part of a journey
Point to next steps
Point to introductory material just in
case
Point to examples

examples A good combination of examples is a
stripped down test case
And one or more applied examples,
showing something more useful
happening

examples
Provide code walkthroughs
Don’t just say “here’s the code to do
that”

examples Real examples are always good
In-page good
IMO, github is best
Codepen. io/jsbin.com work well
alongside it

consistnt Keep everything* consistent
Code style
Document structure
Navigation...

consistnt * Writing style, not so much
Should always be clear and level
But you don’t want it robotised too
much
Especially in a multi-author community

Does humour belong in music?
It certainly belongs in docs
Try to make it as non boring as
possible
Fun makes learning easier

navigate Multiple navigation is good
Let the reader know where they are
Where to go next
How to get back home

navigate Breadcrumb trails
Search
Context menu for overall section
Previous and Next in series
Main menu link

surprises
People don’t like them!

ingeneral Don’t say “Read the source”
Or “Read the Tests”
Don’t assume the reader knows as
much as you
Put yourself in their shoes
Don’t just show them. TEACH them.

Case study

css=hard
Teaching CSS layout

css=hard
They probably know the basics of CSS
already
They should do anyway

css=hard Show them an example?
RTFM?
Show them the spec?
Show them some crazy CSS
framework shizzle?

css=hard Start with a really basic two column
example
Explain how floats work
Show fixed width and liquid layout
Give them step by step, get them to
build it themselves

css=hard Go on to what happens when you try
to add a background colour to the
parent?
Or add further content underneath the
floated elements?

css=hard Why does floating reduce the effective
parent height to zero?
Why is clearing needed? Exactly how
does it work?

css=hard What happens when you actually put
content inside the columns?
(Man, WTF?)
Show box model, how padding/content/
margin all affects the whole shebang

css=hard Advanced stuff
box-sizing: border-box
three columns
RWD
Show common use cases

css=hard
But err on the side of explaining too
much, if you are unsure

css=hard
Set homework!
Push the reader a little further each
time.

Doc archetypes

tutorials Step by step
Practical guide to completing a task
Set audience level, time, prerequisites,
brief background
Focus on the practical
Finish with conclusion, caveats, next
steps, challenges, reference link

guides Overview of an atomic subject
Start with background and problem,
prerequisite knowledge
Give details of solution, explain relevant
features, give simple and expanded code
Finish with conclusion, caveats,
further info links, next steps if needed,
reference link

reference Dry as anything
No background
Just the details
Be comprehensive
Provide basic syntax
Link to examples and guides/tutorials

Licensing

licensing Always go with open licensing
At least for tech docs
Nothing else makes any sense
And means pointless repetition

licensing
Although traditional big business really
doesn’t get it...

licensing For docs, choose something like GPL,
or CC, or MIT license
CC has different flavours
cc-by: attribution
cc-by-sa: attribution and share alike
cc-by-sa-nc: as above +
non-commercial

licensing
Be as open as you can
But get credit where credit is due!

licensing For code examples
Make then cc-0 / public domain
Code is cheap really, in the area of
doc examples

re-use Again, put it on github
Have one canonical version
Others can send pull requests
And still reuse it elsewhere

re-use Even better
Provide an API for others to easily
grab your content
And reuse it elsewhere
MDN API, caniuse.com ...

Finito

thanks!! slideshare.net/chrisdavidmills
cmills@mozilla.com
@chrisdavidmills
http://stevelosh.com/blog/2013/09/
teach-dont-tell/

Documentation and publishing

More Related Content

Viewers also liked

Similar to Documentation and publishing

More from Chris Mills

Recently uploaded

Documentation and publishing