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 whingeb...
Contact
slideshare.net/chrisdavidmills
cmills@mozilla.com
@chrisdavidmills
Monday, 23 September 13
backgrd Mozilla since July 2013
Opera 2007-2013
Apress/friends of ED 2003-2007
Wrox/glasshaus 2000-2003
Monday, 23 Septemb...
backgrd Simon asked me to speak at McrFred
Over a beer or 4
I’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
tradpub Traditional publishing has been around
for 100s of years
Well-established brands like Pearson,
Springer, Oxford Un...
tradpub Subject matter expert provides
knowledge
Publisher provides word craft, guidance,
marketing, distribution, layout,...
tradpub Author gets advance + royalties
Advance has to be earnt out before any
more royalties are earnt
Revenue also comes...
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 luc...
tradpub Popular area (HTML/CSS?)
Niche area that you own
You have personal marketing ability (big
name, lots of mates)
Als...
gotchas You have to watch out for international
tax (e.g. you need an ITIN when
working with US companies)
Many publishers...
gotchas Careful of product quality and ethics
Many publishers check the spelling,
then pour your content into an ugly
temp...
also... A print run is about 3-6000 copies
A huge waste...
...if it contains serious mistakes
...and/or doesn’t sell
Monda...
gotchas Contract bullshit: non-compete
clauses
Liability for project completion
When is the advance paid?
Some publishers ...
Monday, 23 September 13
thisiswhy This is why publishers like Five Simple
Steps and A Book Apart started to
appear
Books by designers, for designe...
trouble
The main trouble is that trad publishing
is no good for fast moving topics like
open standards, even with eBooks, ...
Changing languages
Changing APIs, libraries
Changing standards
Changing browser support
Changing best practices
Aaargh!
Mo...
trouble
And licensing of traditional publishers
tends to be incompatible with open
licensing.
Monday, 23 September 13
self Self publishing solves many problems
Publish as eBook
Print on demand, so no warehouse
stock
And you can update the c...
self Do your own production
Or get someone else to do it
Use a service like Lulu, CreateSpace,
iUniverse, Xlibris...
Monda...
self You could buy your own ISBN and set
up your own publishing house
You’ll need to print it yourself, create
a cover, ge...
self Marketing/distribution is the issue
You need to get it on amazon, B&N,
iTunes, and other main outlets
This is really ...
self Marketing requires some guerrilla action
Set up a site with referral links to buy
Keep promoting it ruthlessly
Keep p...
snook! SMACSS.com is a great case in point
Monday, 23 September 13
piracy ...piracy has never worried me
It actually tends to help
Pirates wouldn’t buy it anyway
It can help get the word ou...
Online publishing
Monday, 23 September 13
online
Blogs
Wikis
Packaged/integrated docs
Monday, 23 September 13
ingeneral Can publish instantly
Can fix instantly
More iterative
Instant wide distribution
Monday, 23 September 13
Blogs
Monday, 23 September 13
blogs Of the moment information
Great for promotion
Great for individual articles
Quick to dream up and publish
Monday, 23...
blogs
Not as immediately collaborative
Not as good for structured docs
Less browsable
Monday, 23 September 13
although
Blogs can turn into books
Or even publishing companies
This is how Five Simple Steps started
Monday, 23 September...
cases A List Apart
Smashing Mag
dev.opera.com
Mozilla Hacks
Monday, 23 September 13
Wikis
Monday, 23 September 13
wikis
Great for collaboration
Great for structuring content
Great for building communities
Monday, 23 September 13
wikis Lots more thought needed
Content quickly becomes a mess
Curation needed
Community building needs love and
attention
...
wikis Wikis do have a stigma
People assume crowd sourced means
low quality and ugly
But you can change that
It’s all about...
cases Wikipedia ;-)
MDN!!
My little pony Wiki, apparently
Any good computer game ever...
Many are really bad
Monday, 23 Se...
Packaged/integrated
Monday, 23 September 13
packaged Why not package docs along with your
product?
Or generate them from the product?
Great for offline use
Always at ...
packaged Need to update docs as you update
distribution
Some systems require building, so make
sure you are clear on instr...
packaged Jekyll (jekyllrb.com/)
Apiary (apiary.io/)
JSDoc (github.com/jsdoc3/jsdoc)
Readthedocs
Sphinx
HTML!
Monday, 23 Se...
packaged A packaged doc format doesn’t allow
collaboration as easily
Although you could allow external
contributions via g...
What’s for the best?
Monday, 23 September 13
hybrid Why not do all three?
feed the same docs into both the
online and offline doc versions
Allow external contributions...
cases Wiki, API to feed packaged docs?
Something like jekyll, hosted on github.
Use that to feed the online version,
then ...
Communities
Monday, 23 September 13
commune Community building is hard
But rewarding
You can get a huge amount of input
But you need to keep nurturing them
Mo...
commune
A community needs a clear purpose
Reason to come back
Rewards
Monday, 23 September 13
commune
Mozilla
Linux/Ubuntu
Opera
Monday, 23 September 13
reasons Fight the power
Collaborate on some work
Achieve a good cause
Common interest
Monday, 23 September 13
rewards Badges (gamification)
Contributor of the week
Schwag
Flights to events
Socialisation (being right)
Monday, 23 Sept...
focii Easy communication (IRC, mailing list)
But not too much
Weekly meetings
Doc Sprints
Monday, 23 September 13
contrib Contributions need some kind of login
To cut down on spam
And make contributions recordable
(blame & reward)
But m...
contrib Edit wars less of a problem than you’d
think
If it gets really bad, you might
have to ban users
temporarily
Monday...
Feedback
Monday, 23 September 13
feedback
Is vital
Is hard to get right
Is a pain in the ass
Monday, 23 September 13
feedback Provide as many feedback mechanisms
as you need
But as few as possible
Each one carries extra overhead
Monday, 23...
feedback Comments (in page?)
Forums (linked to articles?)
Wiki talk pages
IRC/mailing lists
Monday, 23 September 13
feedback Feedback needs to be accessible
Without being too intrusive
How do you get the feedback you
want?
Curation can be...
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...
Content
Monday, 23 September 13
content What constitutes good content?
Content that teaches the target
audience what they need to know as
quickly as possi...
content Focus on a solid atomic subject in
each article.
Not the kitchen sink
And make it meaningful, not “167 best
Web RT...
content If it’s a guide or a tutorial, tell a
story
Build up towards a crescendo, and
ultimate purpose
Make the goal and j...
content
Rambling directionless narratives are
awful
Monday, 23 September 13
content Get your target audience right
Decide what your assumptions are
Think about what style suits them
best
Monday, 23 ...
content Make your article part of a journey
Point to next steps
Point to introductory material just in
case
Point to examp...
examples A good combination of examples is a
stripped down test case
And one or more applied examples,
showing something m...
examples
Provide code walkthroughs
Don’t just say “here’s the code to do
that”
Monday, 23 September 13
examples Real examples are always good
In-page good
IMO, github is best
Codepen. io/jsbin.com work well
alongside it
Monda...
consistnt Keep everything* consistent
Code style
Document structure
Navigation...
Monday, 23 September 13
consistnt * Writing style, not so much
Should always be clear and level
But you don’t want it robotised too
much
Especiall...
Does humour belong in music?
It certainly belongs in docs
Try to make it as non boring as
possible
Fun makes learning easi...
navigate Multiple navigation is good
Let the reader know where they are
Where to go next
How to get back home
Monday, 23 S...
navigate Breadcrumb trails
Search
Context menu for overall section
Previous and Next in series
Main menu link
Monday, 23 S...
Monday, 23 September 13
surprises
People don’t like them!
Monday, 23 September 13
ingeneral Don’t say “Read the source”
Or “Read the Tests”
Don’t assume the reader knows as
much as you
Put yourself in the...
Case study
Monday, 23 September 13
css=hard
Teaching CSS layout
Monday, 23 September 13
css=hard
They probably know the basics of CSS
already
They 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 ...
css=hard Start with a really basic two column
example
Explain how floats work
Show fixed width and liquid layout
Give them...
css=hard Go on to what happens when you try
to add a background colour to the
parent?
Or add further content underneath th...
css=hard Why does floating reduce the effective
parent height to zero?
Why is clearing needed? Exactly how
does it work?
M...
css=hard What happens when you actually put
content inside the columns?
(Man, WTF?)
Show box model, how padding/content/
m...
css=hard Advanced stuff
box-sizing: border-box
three columns
RWD
Show 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
tutorials Step by step
Practical guide to completing a task
Set audience level, time, prerequisites,
brief background
Focu...
guides Overview of an atomic subject
Start with background and problem,
prerequisite knowledge
Give details of solution, e...
reference Dry as anything
No background
Just the details
Be comprehensive
Provide basic syntax
Link to examples and guides...
Licensing
Monday, 23 September 13
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...
Monday, 23 September 13
licensing For docs, choose something like GPL,
or CC, or MIT license
CC has different flavours
cc-by: attribution
cc-by-sa...
licensing
Be as open as you can
But get credit where credit is due!
Monday, 23 September 13
licensing For code examples
Make then cc-0 / public domain
Code is cheap really, in the area of
doc examples
Monday, 23 Se...
re-use Again, put it on github
Have one canonical version
Others can send pull requests
And still reuse it elsewhere
Monda...
re-use Even better
Provide an API for others to easily
grab your content
And reuse it elsewhere
MDN API, caniuse.com ...
M...
Finito
Monday, 23 September 13
thanks!! slideshare.net/chrisdavidmills
cmills@mozilla.com
@chrisdavidmills
http://stevelosh.com/blog/2013/09/
teach-dont-...
Upcoming SlideShare
Loading in...5
×

Documentation and publishing

540

Published on

Published in: Technology, Business, Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
540
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
2
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Documentation and publishing

  1. 1. Docs and publishing McrFred Sep ’13 // Chris Mills, Mozilla Monday, 23 September 13
  2. 2. WhoamI? Senior tech writer @ Formerly tech writer & evangelist @ HTML, CSS, JS and Mobile enthusiast Accessibility whingebag Education agitator Heavy metal geek dad Monday, 23 September 13
  3. 3. Contact slideshare.net/chrisdavidmills cmills@mozilla.com @chrisdavidmills Monday, 23 September 13
  4. 4. backgrd Mozilla since July 2013 Opera 2007-2013 Apress/friends of ED 2003-2007 Wrox/glasshaus 2000-2003 Monday, 23 September 13
  5. 5. backgrd Simon asked me to speak at McrFred Over a beer or 4 I’m setting out to answer a question Monday, 23 September 13
  6. 6. Is documentation really boring? Monday, 23 September 13
  7. 7. Traditional publishing Monday, 23 September 13
  8. 8. tradpub Traditional publishing has been around for 100s of years Well-established brands like Pearson, Springer, Oxford University Press Monday, 23 September 13
  9. 9. tradpub Subject matter expert provides knowledge Publisher provides word craft, guidance, marketing, distribution, layout, production, etc. Monday, 23 September 13
  10. 10. 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. Monday, 23 September 13
  11. 11. 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 Monday, 23 September 13
  12. 12. 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 Monday, 23 September 13
  13. 13. 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 Monday, 23 September 13
  14. 14. 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? Monday, 23 September 13
  15. 15. also... A print run is about 3-6000 copies A huge waste... ...if it contains serious mistakes ...and/or doesn’t sell Monday, 23 September 13
  16. 16. 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 Monday, 23 September 13
  17. 17. Monday, 23 September 13
  18. 18. thisiswhy This is why publishers like Five Simple Steps and A Book Apart started to appear Books by designers, for designers Monday, 23 September 13
  19. 19. 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 Monday, 23 September 13
  20. 20. Changing languages Changing APIs, libraries Changing standards Changing browser support Changing best practices Aaargh! Monday, 23 September 13
  21. 21. trouble And licensing of traditional publishers tends to be incompatible with open licensing. Monday, 23 September 13
  22. 22. self Self publishing solves many problems Publish as eBook Print on demand, so no warehouse stock And you can update the copy when necessary Monday, 23 September 13
  23. 23. self Do your own production Or get someone else to do it Use a service like Lulu, CreateSpace, iUniverse, Xlibris... Monday, 23 September 13
  24. 24. 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... Monday, 23 September 13
  25. 25. 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 Monday, 23 September 13
  26. 26. 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 Monday, 23 September 13
  27. 27. snook! SMACSS.com is a great case in point Monday, 23 September 13
  28. 28. 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 Monday, 23 September 13
  29. 29. Online publishing Monday, 23 September 13
  30. 30. online Blogs Wikis Packaged/integrated docs Monday, 23 September 13
  31. 31. ingeneral Can publish instantly Can fix instantly More iterative Instant wide distribution Monday, 23 September 13
  32. 32. Blogs Monday, 23 September 13
  33. 33. blogs Of the moment information Great for promotion Great for individual articles Quick to dream up and publish Monday, 23 September 13
  34. 34. blogs Not as immediately collaborative Not as good for structured docs Less browsable Monday, 23 September 13
  35. 35. although Blogs can turn into books Or even publishing companies This is how Five Simple Steps started Monday, 23 September 13
  36. 36. cases A List Apart Smashing Mag dev.opera.com Mozilla Hacks Monday, 23 September 13
  37. 37. Wikis Monday, 23 September 13
  38. 38. wikis Great for collaboration Great for structuring content Great for building communities Monday, 23 September 13
  39. 39. 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 Monday, 23 September 13
  40. 40. 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 Monday, 23 September 13
  41. 41. cases Wikipedia ;-) MDN!! My little pony Wiki, apparently Any good computer game ever... Many are really bad Monday, 23 September 13
  42. 42. Packaged/integrated Monday, 23 September 13
  43. 43. packaged Why not package docs along with your product? Or generate them from the product? Great for offline use Always at hand Monday, 23 September 13
  44. 44. 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 Monday, 23 September 13
  45. 45. packaged Jekyll (jekyllrb.com/) Apiary (apiary.io/) JSDoc (github.com/jsdoc3/jsdoc) Readthedocs Sphinx HTML! Monday, 23 September 13
  46. 46. packaged A packaged doc format doesn’t allow collaboration as easily Although you could allow external contributions via github Monday, 23 September 13
  47. 47. What’s for the best? Monday, 23 September 13
  48. 48. 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 Monday, 23 September 13
  49. 49. 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 Monday, 23 September 13
  50. 50. Communities Monday, 23 September 13
  51. 51. commune Community building is hard But rewarding You can get a huge amount of input But you need to keep nurturing them Monday, 23 September 13
  52. 52. commune A community needs a clear purpose Reason to come back Rewards Monday, 23 September 13
  53. 53. commune Mozilla Linux/Ubuntu Opera Monday, 23 September 13
  54. 54. reasons Fight the power Collaborate on some work Achieve a good cause Common interest Monday, 23 September 13
  55. 55. rewards Badges (gamification) Contributor of the week Schwag Flights to events Socialisation (being right) Monday, 23 September 13
  56. 56. focii Easy communication (IRC, mailing list) But not too much Weekly meetings Doc Sprints Monday, 23 September 13
  57. 57. 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 Monday, 23 September 13
  58. 58. contrib Edit wars less of a problem than you’d think If it gets really bad, you might have to ban users temporarily Monday, 23 September 13
  59. 59. Feedback Monday, 23 September 13
  60. 60. feedback Is vital Is hard to get right Is a pain in the ass Monday, 23 September 13
  61. 61. feedback Provide as many feedback mechanisms as you need But as few as possible Each one carries extra overhead Monday, 23 September 13
  62. 62. feedback Comments (in page?) Forums (linked to articles?) Wiki talk pages IRC/mailing lists Monday, 23 September 13
  63. 63. 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 Monday, 23 September 13
  64. 64. 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 Monday, 23 September 13
  65. 65. Content Monday, 23 September 13
  66. 66. content 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
  67. 67. content Focus on a solid atomic subject in each article. Not the kitchen sink And make it meaningful, not “167 best Web RTC demos” Monday, 23 September 13
  68. 68. 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 Monday, 23 September 13
  69. 69. content Rambling directionless narratives are awful Monday, 23 September 13
  70. 70. content Get your target audience right Decide what your assumptions are Think about what style suits them best Monday, 23 September 13
  71. 71. content Make your article part of a journey Point to next steps Point to introductory material just in case Point to examples Monday, 23 September 13
  72. 72. examples A good combination of examples is a stripped down test case And one or more applied examples, showing something more useful happening Monday, 23 September 13
  73. 73. examples Provide code walkthroughs Don’t just say “here’s the code to do that” Monday, 23 September 13
  74. 74. examples Real examples are always good In-page good IMO, github is best Codepen. io/jsbin.com work well alongside it Monday, 23 September 13
  75. 75. consistnt Keep everything* consistent Code style Document structure Navigation... Monday, 23 September 13
  76. 76. 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 Monday, 23 September 13
  77. 77. Does humour belong in music? It certainly belongs in docs Try to make it as non boring as possible Fun makes learning easier Monday, 23 September 13
  78. 78. navigate Multiple navigation is good Let the reader know where they are Where to go next How to get back home Monday, 23 September 13
  79. 79. navigate Breadcrumb trails Search Context menu for overall section Previous and Next in series Main menu link Monday, 23 September 13
  80. 80. Monday, 23 September 13
  81. 81. surprises People don’t like them! Monday, 23 September 13
  82. 82. 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. Monday, 23 September 13
  83. 83. Case study Monday, 23 September 13
  84. 84. css=hard Teaching CSS layout Monday, 23 September 13
  85. 85. css=hard They probably know the basics of CSS already They should do anyway Monday, 23 September 13
  86. 86. css=hard Show them an example? RTFM? Show them the spec? Show them some crazy CSS framework shizzle? Monday, 23 September 13
  87. 87. 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 Monday, 23 September 13
  88. 88. 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
  89. 89. 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
  90. 90. 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
  91. 91. css=hard Advanced stuff box-sizing: border-box three columns RWD Show common use cases Monday, 23 September 13
  92. 92. css=hard But err on the side of explaining too much, if you are unsure Monday, 23 September 13
  93. 93. css=hard Set homework! Push the reader a little further each time. Monday, 23 September 13
  94. 94. Doc archetypes Monday, 23 September 13
  95. 95. 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 Monday, 23 September 13
  96. 96. 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 Monday, 23 September 13
  97. 97. reference Dry as anything No background Just the details Be comprehensive Provide basic syntax Link to examples and guides/tutorials Monday, 23 September 13
  98. 98. Licensing Monday, 23 September 13
  99. 99. licensing Always go with open licensing At least for tech docs Nothing else makes any sense And means pointless repetition Monday, 23 September 13
  100. 100. licensing Although traditional big business really doesn’t get it... Monday, 23 September 13
  101. 101. 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 Monday, 23 September 13
  102. 102. licensing Be as open as you can But get credit where credit is due! Monday, 23 September 13
  103. 103. licensing For code examples Make then cc-0 / public domain Code is cheap really, in the area of doc examples Monday, 23 September 13
  104. 104. re-use Again, put it on github Have one canonical version Others can send pull requests And still reuse it elsewhere Monday, 23 September 13
  105. 105. re-use Even better Provide an API for others to easily grab your content And reuse it elsewhere MDN API, caniuse.com ... Monday, 23 September 13
  106. 106. Finito Monday, 23 September 13
  107. 107. thanks!! slideshare.net/chrisdavidmills cmills@mozilla.com @chrisdavidmills http://stevelosh.com/blog/2013/09/ teach-dont-tell/ Monday, 23 September 13
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×