documentation and publishing

Docs and publishing

McrFred Sep ’13 // Chris Mills, Mozilla

Monday, 23 September 13

Who a

m I? Senior tech writer @

Formerly tech writer & evangelist @ HTML, CSS, JS and Mobile enthusiastAccessibility whingebagEducation agitatorHeavy metal geek dad


Cont

act

slideshare.net/[email protected]@chrisdavidmills


mailto:[email protected]


back

grd Mozilla since July 2013

Opera 2007-2013Apress/friends of ED 2003-2007Wrox/glasshaus 2000-2003


back

grd

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


Is documentation really boring?


Traditional publishing


trad

pub

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


trad

pub

Subject matter expert provides knowledgePublisher provides word craft, guidance, marketing, distribution, layout, production, etc.


trad

pub

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


trad

pub

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


trad

pub

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


gotc

has

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


gotc

has Careful of product quality and ethics

Many publishers check the spelling, then pour your content into an ugly templateBook series, formulaic cover...does this fit your book’s style?


also

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


gotc

has Contract bullshit: non-compete

clausesLiability for project completionWhen is the advance paid?Some publishers sign a bunch of projects, knowing they will can some of the less promising ones


thisi

swhy

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


trou

ble

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 languagesChanging APIs, librariesChanging standardsChanging browser supportChanging best practicesAaargh!


trou

ble

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


self

Self publishing solves many problemsPublish as eBookPrint on demand, so no warehouse stockAnd you can update the copy when necessary


self

Do your own productionOr get someone else to do itUse a service like Lulu, CreateSpace, iUniverse, Xlibris...


self

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


self

Marketing/distribution is the issueYou need to get it on amazon, B&N, iTunes, and other main outletsThis is really just legwork


self

Marketing requires some guerrilla actionSet up a site with referral links to buyKeep promoting it ruthlesslyKeep publishing related articles, do talks, give tidbits away for freeTurn the whole promotion effort into a product


snoo

k! SMACSS.com is a great case in point


pirac

y ...piracy has never worried meIt actually tends to helpPirates wouldn’t buy it anywayIt can help get the word outSome will always want a proper book


Online publishing


onlin

eBlogsWikisPackaged/integrated docs


in ge

nera

lCan publish instantlyCan fix instantlyMore iterativeInstant wide distribution


Blogs


blog

s Of the moment informationGreat for promotionGreat for individual articlesQuick to dream up and publish


blog

s Not as immediately collaborativeNot as good for structured docsLess browsable


alth

ough

Blogs can turn into booksOr even publishing companiesThis is how Five Simple Steps started


case

s A List ApartSmashing Magdev.opera.comMozilla Hacks


Wikis


wiki

s Great for collaborationGreat for structuring contentGreat for building communities


wiki

sLots more thought neededContent quickly becomes a messCuration neededCommunity building needs love and attentionSpamming not necessarily that big a problem


wiki

s Wikis do have a stigmaPeople assume crowd sourced means low quality and uglyBut you can change thatIt’s all about perception


case

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


Packaged/integrated


pack

aged Why not package docs along with your

product?Or generate them from the product?Great for offline useAlways at hand


pack

aged Need to update docs as you update

distributionSome systems require building, so make sure you are clear on instructionsDevelopers are not necessarily the best doc writers


pack

aged Jekyll (jekyllrb.com/)

Apiary (apiary.io/)JSDoc (github.com/jsdoc3/jsdoc)ReadthedocsSphinxHTML!


http://jekyllrb.com

http://jekyllrb.com

http://apiary.io

http://apiary.io

pack

aged

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


What’s for the best?


hybr

id Why not do all three?feed the same docs into both the online and offline doc versionsAllow external contributionsDo regular blog posts to highlight product features or new content


case

s 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


comm

une

Community building is hardBut rewardingYou can get a huge amount of inputBut you need to keep nurturing them


comm

une

A community needs a clear purposeReason to come backRewards


comm

une

MozillaLinux/UbuntuOpera


reas

ons

Fight the powerCollaborate on some workAchieve a good causeCommon interest


rewa

rds

Badges (gamification)Contributor of the weekSchwagFlights to eventsSocialisation (being right)


focii

Easy communication (IRC, mailing list)But not too muchWeekly meetingsDoc Sprints


cont

rib Contributions need some kind of login

To cut down on spamAnd make contributions recordable (blame & reward)But make it as easyas possible


cont

rib Edit wars less of a problem than you’d

thinkIf it gets really bad, you mighthave to ban userstemporarily


Feedback


feed

back

Is vitalIs hard to get rightIs a pain in the ass


feed

back Provide as many feedback mechanisms

as you needBut as few as possibleEach one carries extra overhead


feed

back Comments (in page?)

Forums (linked to articles?)Wiki talk pagesIRC/mailing lists


feed

back Feedback needs to be accessible

Without being too intrusiveHow do you get the feedback you want?Curation can be a massive time-sink


feed

back It needs to work with your workflow

I like to get everything in my inboxIf it’s sat on a forum or bugzilla, then I won’t check it


Content


cont

ent

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


cont

ent

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


cont

ent If it’s a guide or a tutorial, tell a

storyBuild up towards a crescendo, and ultimate purposeMake the goal and journey clear at the start


cont

ent

Rambling directionless narratives are awful


cont

ent

Get your target audience rightDecide what your assumptions areThink about what style suits them best


cont

ent Make your article part of a journey

Point to next stepsPoint to introductory material just in casePoint to examples


exam

ples A good combination of examples is a

stripped down test caseAnd one or more applied examples, showing something more useful happening


exam

ples

Provide code walkthroughsDon’t just say “here’s the code to do that”


exam

ples Real examples are always good

In-page goodIMO, github is bestCodepen. io/jsbin.com work well alongside it


cons

istnt

Keep everything* consistentCode styleDocument structureNavigation...


cons

istnt * Writing style, not so much

Should always be clear and levelBut you don’t want it robotised too muchEspecially in a multi-author community


Does humour belong in music?It certainly belongs in docsTry to make it as non boring as possibleFun makes learning easier


navi

gate Multiple navigation is good

Let the reader know where they areWhere to go nextHow to get back home


navi

gate Breadcrumb trails

SearchContext menu for overall sectionPrevious and Next in seriesMain menu link


surp

rise

sPeople don’t like them!


in ge

nera

lDon’t say “Read the source”Or “Read the Tests”Don’t assume the reader knows as much as youPut yourself in their shoesDon’t just show them. TEACH them.


Case study


css =

hard

Teaching CSS layout


css =

hard

They probably know the basics of CSS alreadyThey 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

exampleExplain how floats workShow fixed width and liquid layoutGive 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-boxthree columnsRWDShow 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


tuto

rial

s Step by stepPractical guide to completing a taskSet audience level, time, prerequisites, brief backgroundFocus on the practicalFinish with conclusion, caveats, next steps, challenges, reference link


guid

esOverview of an atomic subjectStart with background and problem, prerequisite knowledgeGive details of solution, explain relevant features, give simple and expanded codeFinish with conclusion, caveats, further info links, next steps if needed, reference link


refe

renc

eDry as anythingNo backgroundJust the detailsBe comprehensiveProvide basic syntaxLink to examples and guides/tutorials


Licensing


licen

sing

Always go with open licensingAt least for tech docsNothing else makes any senseAnd means pointless repetition


licen

sing

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


licen

sing For docs, choose something like GPL,

or CC, or MIT licenseCC has different flavourscc-by: attributioncc-by-sa: attribution and share alikecc-by-sa-nc: as above +non-commercial


licen

sing

Be as open as you canBut get credit where credit is due!


licen

sing

For code examplesMake then cc-0 / public domainCode is cheap really, in the area of doc examples


re-u

se Again, put it on githubHave one canonical versionOthers can send pull requestsAnd still reuse it elsewhere


re-u

se Even betterProvide an API for others to easily grab your contentAnd reuse it elsewhereMDN API, caniuse.com ...


Finito


than

ks!! slideshare.net/chrisdavidmills

[email protected]@chrisdavidmillshttp://stevelosh.com/blog/2013/09/teach-dont-tell/




http://stevelosh.com/blog/2013/09/teach-dont-tell/




documentation and publishing

Technology