documentation and publishing
TRANSCRIPT
![Page 1: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/1.jpg)
Docs and publishing
McrFred Sep ’13 // Chris Mills, Mozilla
Monday, 23 September 13
![Page 2: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/2.jpg)
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
![Page 4: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/4.jpg)
back
grd Mozilla since July 2013
Opera 2007-2013Apress/friends of ED 2003-2007Wrox/glasshaus 2000-2003
Monday, 23 September 13
![Page 5: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/5.jpg)
back
grd
Simon asked me to speak at McrFredOver a beer or 4I’m setting out to answer a question
Monday, 23 September 13
![Page 6: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/6.jpg)
Is documentation really boring?
Monday, 23 September 13
![Page 7: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/7.jpg)
Traditional publishing
Monday, 23 September 13
![Page 8: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/8.jpg)
trad
pub
Traditional publishing has been around for 100s of yearsWell-established brands like Pearson, Springer, Oxford University Press
Monday, 23 September 13
![Page 9: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/9.jpg)
trad
pub
Subject matter expert provides knowledgePublisher provides word craft, guidance, marketing, distribution, layout, production, etc.
Monday, 23 September 13
![Page 10: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/10.jpg)
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
![Page 11: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/11.jpg)
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
![Page 12: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/12.jpg)
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
![Page 13: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/13.jpg)
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
![Page 14: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/14.jpg)
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
![Page 15: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/15.jpg)
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
![Page 16: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/16.jpg)
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
![Page 17: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/17.jpg)
Monday, 23 September 13
![Page 18: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/18.jpg)
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
![Page 19: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/19.jpg)
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
![Page 20: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/20.jpg)
Changing languagesChanging APIs, librariesChanging standardsChanging browser supportChanging best practicesAaargh!
Monday, 23 September 13
![Page 21: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/21.jpg)
trou
ble
And licensing of traditional publishers tends to be incompatible with open licensing.
Monday, 23 September 13
![Page 22: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/22.jpg)
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
![Page 23: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/23.jpg)
self
Do your own productionOr get someone else to do itUse a service like Lulu, CreateSpace, iUniverse, Xlibris...
Monday, 23 September 13
![Page 24: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/24.jpg)
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
![Page 25: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/25.jpg)
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
![Page 26: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/26.jpg)
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
![Page 27: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/27.jpg)
snoo
k! SMACSS.com is a great case in point
Monday, 23 September 13
![Page 28: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/28.jpg)
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
![Page 29: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/29.jpg)
Online publishing
Monday, 23 September 13
![Page 30: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/30.jpg)
onlin
eBlogsWikisPackaged/integrated docs
Monday, 23 September 13
![Page 31: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/31.jpg)
in ge
nera
lCan publish instantlyCan fix instantlyMore iterativeInstant wide distribution
Monday, 23 September 13
![Page 32: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/32.jpg)
Blogs
Monday, 23 September 13
![Page 33: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/33.jpg)
blog
s Of the moment informationGreat for promotionGreat for individual articlesQuick to dream up and publish
Monday, 23 September 13
![Page 34: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/34.jpg)
blog
s Not as immediately collaborativeNot as good for structured docsLess browsable
Monday, 23 September 13
![Page 35: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/35.jpg)
alth
ough
Blogs can turn into booksOr even publishing companiesThis is how Five Simple Steps started
Monday, 23 September 13
![Page 36: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/36.jpg)
case
s A List ApartSmashing Magdev.opera.comMozilla Hacks
Monday, 23 September 13
![Page 37: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/37.jpg)
Wikis
Monday, 23 September 13
![Page 38: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/38.jpg)
wiki
s Great for collaborationGreat for structuring contentGreat for building communities
Monday, 23 September 13
![Page 39: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/39.jpg)
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
![Page 40: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/40.jpg)
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
![Page 41: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/41.jpg)
case
s Wikipedia ;-)MDN!!My little pony Wiki, apparentlyAny good computer game ever...Many are really bad
Monday, 23 September 13
![Page 42: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/42.jpg)
Packaged/integrated
Monday, 23 September 13
![Page 43: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/43.jpg)
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
![Page 44: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/44.jpg)
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
![Page 45: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/45.jpg)
pack
aged Jekyll (jekyllrb.com/)
Apiary (apiary.io/)JSDoc (github.com/jsdoc3/jsdoc)ReadthedocsSphinxHTML!
Monday, 23 September 13
![Page 46: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/46.jpg)
pack
aged
A packaged doc format doesn’t allow collaboration as easilyAlthough you could allow external contributions via github
Monday, 23 September 13
![Page 47: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/47.jpg)
What’s for the best?
Monday, 23 September 13
![Page 48: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/48.jpg)
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
![Page 49: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/49.jpg)
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
![Page 50: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/50.jpg)
Communities
Monday, 23 September 13
![Page 51: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/51.jpg)
comm
une
Community building is hardBut rewardingYou can get a huge amount of inputBut you need to keep nurturing them
Monday, 23 September 13
![Page 52: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/52.jpg)
comm
une
A community needs a clear purposeReason to come backRewards
Monday, 23 September 13
![Page 53: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/53.jpg)
comm
une
MozillaLinux/UbuntuOpera
Monday, 23 September 13
![Page 54: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/54.jpg)
reas
ons
Fight the powerCollaborate on some workAchieve a good causeCommon interest
Monday, 23 September 13
![Page 55: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/55.jpg)
rewa
rds
Badges (gamification)Contributor of the weekSchwagFlights to eventsSocialisation (being right)
Monday, 23 September 13
![Page 56: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/56.jpg)
focii
Easy communication (IRC, mailing list)But not too muchWeekly meetingsDoc Sprints
Monday, 23 September 13
![Page 57: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/57.jpg)
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
![Page 58: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/58.jpg)
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
![Page 59: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/59.jpg)
Feedback
Monday, 23 September 13
![Page 60: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/60.jpg)
feed
back
Is vitalIs hard to get rightIs a pain in the ass
Monday, 23 September 13
![Page 61: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/61.jpg)
feed
back Provide as many feedback mechanisms
as you needBut as few as possibleEach one carries extra overhead
Monday, 23 September 13
![Page 62: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/62.jpg)
feed
back Comments (in page?)
Forums (linked to articles?)Wiki talk pagesIRC/mailing lists
Monday, 23 September 13
![Page 63: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/63.jpg)
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
![Page 64: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/64.jpg)
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
![Page 65: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/65.jpg)
Content
Monday, 23 September 13
![Page 66: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/66.jpg)
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
![Page 67: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/67.jpg)
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
![Page 68: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/68.jpg)
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
![Page 69: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/69.jpg)
cont
ent
Rambling directionless narratives are awful
Monday, 23 September 13
![Page 70: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/70.jpg)
cont
ent
Get your target audience rightDecide what your assumptions areThink about what style suits them best
Monday, 23 September 13
![Page 71: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/71.jpg)
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
![Page 72: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/72.jpg)
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
![Page 73: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/73.jpg)
exam
ples
Provide code walkthroughsDon’t just say “here’s the code to do that”
Monday, 23 September 13
![Page 74: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/74.jpg)
exam
ples Real examples are always good
In-page goodIMO, github is bestCodepen. io/jsbin.com work well alongside it
Monday, 23 September 13
![Page 75: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/75.jpg)
cons
istnt
Keep everything* consistentCode styleDocument structureNavigation...
Monday, 23 September 13
![Page 76: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/76.jpg)
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
![Page 77: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/77.jpg)
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
![Page 78: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/78.jpg)
navi
gate Multiple navigation is good
Let the reader know where they areWhere to go nextHow to get back home
Monday, 23 September 13
![Page 79: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/79.jpg)
navi
gate Breadcrumb trails
SearchContext menu for overall sectionPrevious and Next in seriesMain menu link
Monday, 23 September 13
![Page 80: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/80.jpg)
Monday, 23 September 13
![Page 81: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/81.jpg)
surp
rise
sPeople don’t like them!
Monday, 23 September 13
![Page 82: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/82.jpg)
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
![Page 83: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/83.jpg)
Case study
Monday, 23 September 13
![Page 84: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/84.jpg)
css =
hard
Teaching CSS layout
Monday, 23 September 13
![Page 85: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/85.jpg)
css =
hard
They probably know the basics of CSS alreadyThey should do anyway
Monday, 23 September 13
![Page 86: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/86.jpg)
css =
hard Show them an example?
RTFM?Show them the spec?Show them some crazy CSS framework shizzle?
Monday, 23 September 13
![Page 87: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/87.jpg)
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
![Page 88: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/88.jpg)
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
![Page 89: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/89.jpg)
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
![Page 90: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/90.jpg)
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
![Page 91: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/91.jpg)
css =
hard Advanced stuff
box-sizing: border-boxthree columnsRWDShow common use cases
Monday, 23 September 13
![Page 92: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/92.jpg)
css =
hard
But err on the side of explaining too much, if you are unsure
Monday, 23 September 13
![Page 93: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/93.jpg)
css =
hard
Set homework!Push the reader a little further each time.
Monday, 23 September 13
![Page 94: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/94.jpg)
Doc archetypes
Monday, 23 September 13
![Page 95: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/95.jpg)
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
![Page 96: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/96.jpg)
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
![Page 97: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/97.jpg)
refe
renc
eDry as anythingNo backgroundJust the detailsBe comprehensiveProvide basic syntaxLink to examples and guides/tutorials
Monday, 23 September 13
![Page 98: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/98.jpg)
Licensing
Monday, 23 September 13
![Page 99: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/99.jpg)
licen
sing
Always go with open licensingAt least for tech docsNothing else makes any senseAnd means pointless repetition
Monday, 23 September 13
![Page 100: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/100.jpg)
licen
sing
Although traditional big business really doesn’t get it...
Monday, 23 September 13
![Page 101: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/101.jpg)
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
![Page 102: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/102.jpg)
licen
sing
Be as open as you canBut get credit where credit is due!
Monday, 23 September 13
![Page 103: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/103.jpg)
licen
sing
For code examplesMake then cc-0 / public domainCode is cheap really, in the area of doc examples
Monday, 23 September 13
![Page 104: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/104.jpg)
re-u
se Again, put it on githubHave one canonical versionOthers can send pull requestsAnd still reuse it elsewhere
Monday, 23 September 13
![Page 105: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/105.jpg)
re-u
se Even betterProvide an API for others to easily grab your contentAnd reuse it elsewhereMDN API, caniuse.com ...
Monday, 23 September 13
![Page 106: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/106.jpg)
Finito
Monday, 23 September 13
![Page 107: Documentation and publishing](https://reader031.vdocuments.mx/reader031/viewer/2022013013/58ae44ef1a28abad338b5927/html5/thumbnails/107.jpg)
than
ks!! slideshare.net/chrisdavidmills
[email protected]@chrisdavidmillshttp://stevelosh.com/blog/2013/09/teach-dont-tell/
Monday, 23 September 13