Documentation and publishing
-
Upload
chris-mills -
Category
Technology
-
view
878 -
download
0
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
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
than
ks!! slideshare.net/chrisdavidmills
[email protected]@chrisdavidmillshttp://stevelosh.com/blog/2013/09/teach-dont-tell/
Monday, 23 September 13