Documentation and publishing

Post on 23-Feb-2017

889 views 0 download

Transcript of 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

Monday, 23 September 13

Cont

act

slideshare.net/chrisdavidmillscmills@mozilla.com@chrisdavidmills

Monday, 23 September 13

back

grd Mozilla since July 2013

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

Monday, 23 September 13

back

grd

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

Monday, 23 September 13

Is documentation really boring?

Monday, 23 September 13

Traditional publishing

Monday, 23 September 13

trad

pub

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

Monday, 23 September 13

trad

pub

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

Monday, 23 September 13

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.

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

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?

Monday, 23 September 13

also

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

Monday, 23 September 13

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

Monday, 23 September 13

Monday, 23 September 13

thisi

swhy

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

Monday, 23 September 13

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

Monday, 23 September 13

Changing languagesChanging APIs, librariesChanging standardsChanging browser supportChanging best practicesAaargh!

Monday, 23 September 13

trou

ble

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

Monday, 23 September 13

self

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

Monday, 23 September 13

self

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

Monday, 23 September 13

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

Monday, 23 September 13

self

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

Monday, 23 September 13

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

Monday, 23 September 13

snoo

k! SMACSS.com is a great case in point

Monday, 23 September 13

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

Monday, 23 September 13

Online publishing

Monday, 23 September 13

onlin

eBlogsWikisPackaged/integrated docs

Monday, 23 September 13

in ge

nera

lCan publish instantlyCan fix instantlyMore iterativeInstant wide distribution

Monday, 23 September 13

Blogs

Monday, 23 September 13

blog

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

Monday, 23 September 13

blog

s Not as immediately collaborativeNot as good for structured docsLess browsable

Monday, 23 September 13

alth

ough

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

Monday, 23 September 13

case

s A List ApartSmashing Magdev.opera.comMozilla Hacks

Monday, 23 September 13

Wikis

Monday, 23 September 13

wiki

s Great for collaborationGreat for structuring contentGreat for building communities

Monday, 23 September 13

wiki

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

Monday, 23 September 13

wiki

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

Monday, 23 September 13

case

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

Monday, 23 September 13

Packaged/integrated

Monday, 23 September 13

pack

aged Why not package docs along with your

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

Monday, 23 September 13

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

Monday, 23 September 13

pack

aged Jekyll (jekyllrb.com/)

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

Monday, 23 September 13

pack

aged

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

Monday, 23 September 13

What’s for the best?

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

Communities

Monday, 23 September 13

comm

une

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

Monday, 23 September 13

comm

une

A community needs a clear purposeReason to come backRewards

Monday, 23 September 13

comm

une

MozillaLinux/UbuntuOpera

Monday, 23 September 13

reas

ons

Fight the powerCollaborate on some workAchieve a good causeCommon interest

Monday, 23 September 13

rewa

rds

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

Monday, 23 September 13

focii

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

Monday, 23 September 13

cont

rib Contributions need some kind of login

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

Monday, 23 September 13

cont

rib Edit wars less of a problem than you’d

thinkIf it gets really bad, you mighthave to ban userstemporarily

Monday, 23 September 13

Feedback

Monday, 23 September 13

feed

back

Is vitalIs hard to get rightIs a pain in the ass

Monday, 23 September 13

feed

back Provide as many feedback mechanisms

as you needBut as few as possibleEach one carries extra overhead

Monday, 23 September 13

feed

back Comments (in page?)

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

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

Content

Monday, 23 September 13

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.

Monday, 23 September 13

cont

ent

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

Monday, 23 September 13

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

Monday, 23 September 13

cont

ent

Rambling directionless narratives are awful

Monday, 23 September 13

cont

ent

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

Monday, 23 September 13

cont

ent Make your article part of a journey

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

Monday, 23 September 13

exam

ples A good combination of examples is a

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

Monday, 23 September 13

exam

ples

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

Monday, 23 September 13

exam

ples Real examples are always good

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

Monday, 23 September 13

cons

istnt

Keep everything* consistentCode styleDocument structureNavigation...

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

navi

gate Multiple navigation is good

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

Monday, 23 September 13

navi

gate Breadcrumb trails

SearchContext menu for overall sectionPrevious and Next in seriesMain menu link

Monday, 23 September 13

Monday, 23 September 13

surp

rise

sPeople don’t like them!

Monday, 23 September 13

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.

Monday, 23 September 13

Case study

Monday, 23 September 13

css =

hard

Teaching CSS layout

Monday, 23 September 13

css =

hard

They probably know the basics of CSS alreadyThey should do anyway

Monday, 23 September 13

css =

hard Show them an example?

RTFM?Show them the spec?Show them some crazy CSS framework shizzle?

Monday, 23 September 13

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

Monday, 23 September 13

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?

Monday, 23 September 13

css =

hard

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

Monday, 23 September 13

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

Monday, 23 September 13

css =

hard Advanced stuff

box-sizing: border-boxthree columnsRWDShow common use cases

Monday, 23 September 13

css =

hard

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

Monday, 23 September 13

css =

hard

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

Monday, 23 September 13

Doc archetypes

Monday, 23 September 13

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

Monday, 23 September 13

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

Monday, 23 September 13

refe

renc

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

Monday, 23 September 13

Licensing

Monday, 23 September 13

licen

sing

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

Monday, 23 September 13

licen

sing

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

Monday, 23 September 13

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

Monday, 23 September 13

licen

sing

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

Monday, 23 September 13

licen

sing

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

Monday, 23 September 13

re-u

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

Monday, 23 September 13

re-u

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

Monday, 23 September 13

Finito

Monday, 23 September 13