Documentation and publishing
Upcoming SlideShare
Loading in...5
×
 

Documentation and publishing

on

  • 557 views

 

Statistics

Views

Total Views
557
Views on SlideShare
557
Embed Views
0

Actions

Likes
1
Downloads
2
Comments
0

0 Embeds 0

No embeds

Accessibility

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Documentation and publishing Documentation and publishing Presentation Transcript

  • 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 whingebag Education agitator Heavy metal geek dad Monday, 23 September 13
  • 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 September 13
  • 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 University Press Monday, 23 September 13
  • tradpub Subject matter expert provides knowledge Publisher provides word craft, guidance, marketing, distribution, layout, production, etc. Monday, 23 September 13
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • Monday, 23 September 13
  • 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
  • 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
  • Changing languages Changing APIs, libraries Changing standards Changing browser support Changing best practices Aaargh! Monday, 23 September 13
  • 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 copy when necessary Monday, 23 September 13
  • self Do your own production Or get someone else to do it Use a service like Lulu, CreateSpace, iUniverse, Xlibris... Monday, 23 September 13
  • 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
  • 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
  • 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
  • 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 out Some will always want a proper book Monday, 23 September 13
  • 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 September 13
  • 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 13
  • 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 Spamming not necessarily that big a problem Monday, 23 September 13
  • 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
  • cases Wikipedia ;-) MDN!! My little pony Wiki, apparently Any good computer game ever... Many are really bad Monday, 23 September 13
  • 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 hand Monday, 23 September 13
  • 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
  • packaged Jekyll (jekyllrb.com/) Apiary (apiary.io/) JSDoc (github.com/jsdoc3/jsdoc) Readthedocs Sphinx HTML! Monday, 23 September 13
  • packaged A packaged doc format doesn’t allow collaboration as easily Although you could allow external contributions via github Monday, 23 September 13
  • 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 Do regular blog posts to highlight product features or new content Monday, 23 September 13
  • 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
  • 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 Monday, 23 September 13
  • 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 September 13
  • 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 make it as easy as possible Monday, 23 September 13
  • 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
  • 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 September 13
  • 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 a massive time-sink Monday, 23 September 13
  • 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
  • Content Monday, 23 September 13
  • 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
  • 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
  • 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
  • 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 September 13
  • 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
  • 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
  • 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 Monday, 23 September 13
  • 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 Especially in a multi-author community Monday, 23 September 13
  • 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
  • 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
  • navigate Breadcrumb trails Search Context menu for overall section Previous and Next in series Main menu link Monday, 23 September 13
  • 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 their shoes Don’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 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 13
  • 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
  • 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-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 Focus on the practical Finish with conclusion, caveats, next steps, challenges, reference link Monday, 23 September 13
  • 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
  • reference Dry as anything No background Just the details Be comprehensive Provide basic syntax Link to examples and guides/tutorials Monday, 23 September 13
  • 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 Monday, 23 September 13
  • 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: attribution and share alike cc-by-sa-nc: as above + non-commercial Monday, 23 September 13
  • 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 September 13
  • 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
  • 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
  • Finito Monday, 23 September 13
  • thanks!! slideshare.net/chrisdavidmills cmills@mozilla.com @chrisdavidmills http://stevelosh.com/blog/2013/09/ teach-dont-tell/ Monday, 23 September 13