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
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. tradpub Subject matter expert provides
knowledge
Publisher provides word craft, guidance,
marketing, distribution, layout,
production, etc.
Monday, 23 September 13
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. 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. 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. 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. 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. 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. 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
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. 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. Changing languages
Changing APIs, libraries
Changing standards
Changing browser support
Changing best practices
Aaargh!
Monday, 23 September 13
21. trouble
And licensing of traditional publishers
tends to be incompatible with open
licensing.
Monday, 23 September 13
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. 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. 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. 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. 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
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
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. 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. cases Wikipedia ;-)
MDN!!
My little pony Wiki, apparently
Any good computer game ever...
Many are really bad
Monday, 23 September 13
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. 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
46. packaged A packaged doc format doesn’t allow
collaboration as easily
Although you could allow external
contributions via github
Monday, 23 September 13
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. 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
56. focii Easy communication (IRC, mailing list)
But not too much
Weekly meetings
Doc Sprints
Monday, 23 September 13
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. 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
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. feedback Comments (in page?)
Forums (linked to articles?)
Wiki talk pages
IRC/mailing lists
Monday, 23 September 13
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. 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
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. 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. 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
70. content Get your target audience right
Decide what your assumptions are
Think about what style suits them
best
Monday, 23 September 13
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. 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
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. 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. 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
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
86. css=hard Show them an example?
RTFM?
Show them the spec?
Show them some crazy CSS
framework shizzle?
Monday, 23 September 13
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. 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. 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. 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
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. 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. reference Dry as anything
No background
Just the details
Be comprehensive
Provide basic syntax
Link to examples and guides/tutorials
Monday, 23 September 13
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. licensing
Be as open as you can
But get credit where credit is due!
Monday, 23 September 13
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. 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. 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
