• Like
  • Save
5 Tips for Writing Terrible Documentation
Upcoming SlideShare
Loading in...5
×
 

5 Tips for Writing Terrible Documentation

on

  • 2,199 views

One of the biggest risks facing open source is that its documentation is becoming too good and easy to understand. In this presentation, we'll look at what makes closed-source documentation so shitty, ...

One of the biggest risks facing open source is that its documentation is becoming too good and easy to understand. In this presentation, we'll look at what makes closed-source documentation so shitty, and what we can learn to make our documentation even shittier.

Statistics

Views

Total Views
2,199
Views on SlideShare
2,177
Embed Views
22

Actions

Likes
4
Downloads
24
Comments
0

6 Embeds 22

http://coderwall.com 10
http://www.sfexception.com 6
http://twitter.com 2
http://py1m211.pbworks.com 2
http://a0.twimg.com 1
http://www.linkedin.com 1

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

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
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n

5 Tips for Writing Terrible Documentation 5 Tips for Writing Terrible Documentation Presentation Transcript

  • 5 Easy Ways to Revolutionize your Open Source Project by Writing Terrible Documentation Ryan Weaver @weaverryan
  • Who is this dude? http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation• Core Symfony2 contributor http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation• Core Symfony2 contributor• CEO KnpLabs US http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation• Core Symfony2 contributor• CEO KnpLabs US• Boyfriend of the much more talented @leannapelham http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation• Core Symfony2 contributor• CEO KnpLabs US• Boyfriend of the much more talented @leannapelham http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Who is this dude?• Co-author of the Symfony2 Documentation If you like the presentation,• Core Symfony2 contributor :) she gets the iPad• CEO KnpLabs US• Boyfriend of the much more talented @leannapelham http://www.knplabs.com/en http://www.twitter.com/weaverryan http://www.github.com/weaverryan
  • Act 1:Why good documentation isthe worst thing since “goto”
  • FU Good DocsGood documentation makes your users weak-minded
  • Put your suit and tie on and join us in the penthouse
  • Put your suit and tie on and join us in the penthouseEnterprise Businesses LOVE Shitty Documentation
  • p i e sH i p
  • Who can I make the check out to sir?
  • Who can I make the check out to sir?
  • Who can I make the check out to sir?
  • Act 2:I’m sold! But how can *I* write shitty documentation?
  • Expert Tip #1Don’t write *any*Documentation
  • Why no docs?
  • Why no docs?• You’re a genius - your time shouldbe spent writing the code only
  • Why no docs?• You’re a genius - your time shouldbe spent writing the code only• Your code is the most beautifulcode ever written - why deprive yourusers of needing to look through it?
  • Why no docs?static function load($class){    if (strtolower(substr($class, 0, 6)) !== pear2) { • You’re a genius - your time should        return false;    }    $file = str_replace(array(_, ), DIRECTORY_SEPARATOR, $class) . .php; be spent writing the code only    foreach (self::$paths as $path) {        if (file_exists($path . DIRECTORY_SEPARATOR . $file)) { OMFG your code is awesome!            require $path . DIRECTORY_SEPARATOR . $file;            if (!class_exists($class, false) && !interface_exists($class, false)) { • Your code is the most beautiful                die(new Exception(Class  . $class .  was not present in  .                    $path . DIRECTORY_SEPARATOR . $file .                    ") [PEAR2_Autoload-0.2.3])); code ever written - why deprive your            }            return true; users of needing to look through it?        }    } // ...}
  • Expert Tip #2*Never* proofread your Documentation
  • Perfection on the first try
  • Perfection on the first try “Documentation is like a dream - it’s the raw expression of how yousubconsciously want your application to work. Proofreading it clouds that interpretation and abstracts away from its perfection”
  • Perfection on the first try “Documentation is like a dream - it’s the raw expression of how yousubconsciously want your application to work. Proofreading it clouds that interpretation and abstracts away from its perfection” ~ Me (a quote I made up this morning instead of writing documentation)
  • • Smart guys/gals like you don’t makemistakes, so get back to coding bro!
  • • Smart guys/gals like you don’t makemistakes, so get back to coding bro!• Typos show us that you’re human - that youhave a sensitive side
  • • Smart guys/gals like you don’t make mistakes, so get back to coding bro! • Typos show us that you’re human - that you have a sensitive sideBe aware that teh initial release...
  • • Smart guys/gals like you don’t make mistakes, so get back to coding bro! • Typos show us that you’re human - that you have a sensitive sideBe aware that teh initial release...
  • • Smart guys/gals like you don’t make mistakes, so get back to coding bro! • Typos show us that you’re human - that you have a sensitive side Be aware that teh initial release...He probably criesduring romantic comedies
  • • Smart guys/gals like you don’t make mistakes, so get back to coding bro! • Typos show us that you’re human - that you have a sensitive side Be aware that teh initial release...He probably cries ... I cry duringduring romantic romantic comedies comedies
  • • Smart guys/gals like you don’t make mistakes, so get back to coding bro! • Typos show us that you’re human - that you have a sensitive side Be aware that teh initial release...He probably cries Let’s use his ... I cry duringduring romantic library for our big romantic comedies comedies expensive project!
  • Expert Tip #3Theory over Practice
  • PhD Program in YourLib
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problems
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problemsWhat they really want is:
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problemsWhat they really want is: * an extensive lecture of the theory behind your software
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problemsWhat they really want is: * an extensive lecture of the theory behind your software * code-examples that are absent or - at the very least - ridiculously difficult to find
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problemsWhat they really want is: * an extensive lecture of the theory behind your software * code-examples that are absent or - at the very least - ridiculously difficult to find * to spend hours reading before ever seeing one working example
  • PhD Program in YourLibGuess What? Your users aren’t using yourlibrary to solve their business problems i t! !!What they really want is: se e Let’s * an extensive lecture of the theory behind L your software - E W * code-examples that are absent or - at the K very least - ridiculously difficult to find * to spend hours reading before ever seeing one working example
  • Example: WAY Too EasyImagine is an Image manipulation library for PHP 5.3 inspired by PythonsPIL and other image libraries.Here’s how you can use it:<?phpuse ImagineImageBox;use ImagineImagePoint;$imagine = new ImagineImagickImagine();$image = $imagine->open(/path/to/image.jpg);$image->resize(new Box(15, 25)) ->rotate(45) ->crop(new Point(0, 0), new Box(45, 45)) ->save(/path/to/new/image.jpg);
  • Example: WAY Too EasyImagine is an Image manipulation library for PHP 5.3 inspired by PythonsPIL and other image libraries.Here’s how you can use it:<?phpuse ImagineImageBox;use ImagineImagePoint;$imagine = new ImagineImagickImagine();$image = $imagine->open(/path/to/image.jpg);$image->resize(new Box(15, 25)) ->rotate(45) ->crop(new Point(0, 0), new Box(45, 45)) ->save(/path/to/new/image.jpg);
  • My Awesome LibraryImage manipulation library for PHP 5.3 inspired by Pythons PIL and other image libraries.Basic PrinciplesThe main purpose of Imagine is to provide all the necessary functionality to bring all native low level image processing libraries in PHP to the same simple andintuitive OO API. Several things are necessary to accomplish that such as image manipulation tools (resize, crop, etc). There is always a drawing API, which is animportant object-oriented way for creating basic shapes and advanced charts. You can also write text on an image while still being abstracted away from.When you talk about image manipulation, you should also talk about masking functionality and the theories behind it. In computer science, a mask is data that isused for bitwise operations. Using a mask, multiple bits in a byte, nibble, word can be set either on, off or inverted from on to off (or vice versa) in a single bitwiseoperation. You have the ability to apply black&white or grayscale images as masks, leading to semi-transparency or absolute transparency of the image the mask isbeing applied to.PhilosophyAt AcmeCompany we’ve been discussing the idea of accessing acme data via APIs inside Acme and with some of our community for a while. In theory it’s easy to do– in fact we already have an API working together with access via OAuth which we are using for testing internally at AcmeCompany.However there are 3 things we want to get right before we open up access to our community to use the API: 1. We want to make sure that we’ve addressed all the privacy concerns with allowing 3rd parties to access some or all of this data. And we want to be sure that the Terms & Conditions protect the users data from being misused. 2. We want to give out some example code 3. We want to make sure our documentation is goodI’ve said “privacy concerns” so I expect some of you are worried straight away so I’ll expand on this and give a couple examples:RequirementsThe Imagine library has the following requirements: • PHP 5.3+Depending on the chosen Image implementation, you may need one of the following: • GD2
  • My Awesome LibraryImage manipulation library for PHP 5.3 inspired by Pythons PIL and other image libraries.Basic PrinciplesThe main purpose of Imagine is to provide all the necessary functionality to bring all native low level image processing libraries in PHP to the same simple andintuitive OO API. Several things are necessary to accomplish that such as image manipulation tools (resize, crop, etc). There is always a drawing API, which is animportant object-oriented way for creating basic shapes and advanced charts. You can also write text on an image while still being abstracted away from.When you talk about image manipulation, you should also talk about masking functionality and the theories behind it. In computer science, a mask is data that isused for bitwise operations. Using a mask, multiple bits in a byte, nibble, word can be set either on, off or inverted from on to off (or vice versa) in a single bitwiseoperation. You have the ability to apply black&white or grayscale images as masks, leading to semi-transparency or absolute transparency of the image the mask isbeing applied to.Philosophy Theory first: It’s importantAt AcmeCompany we’ve been discussing the idea of accessing acme data via APIs inside Acme and with some of our community for a while. In theory it’s easy to do– in fact we already have an API working together with access via OAuth which we are using for testing internally at AcmeCompany. 1. to confuse your usersHowever there are 3 things we want to get right before we open up access to our community to use the API: We want to make sure that we’ve addressed all the privacy concerns with allowing 3rd parties to access some or all of this data. And we want to be sure that the Terms & Conditions protect the users data from being misused. 2. We want to give out some example code 3. We want to make sure our documentation is goodI’ve said “privacy concerns” so I expect some of you are worried straight away so I’ll expand on this and give a couple examples:RequirementsThe Imagine library has the following requirements: • PHP 5.3+Depending on the chosen Image implementation, you may need one of the following: • GD2
  • My Awesome LibraryImage manipulation library for PHP 5.3 inspired by Pythons PIL and other image libraries.Basic PrinciplesThe main purpose of Imagine is to provide all the necessary functionality to bring all native low level image processing libraries in PHP to the same simple and Theory first: It’s importantintuitive OO API. Several things are necessary to accomplish that such as image manipulation tools (resize, crop, etc). There is always a drawing API, which is animportant object-oriented way for creating basic shapes and advanced charts. You can also write text on an image while still being abstracted away from.When you talk about image manipulation, you should also talk about masking functionality and the theories behind it. In computer science, a mask is data that isused for bitwise operations. Using a mask, multiple bits in a byte, nibble, word can be set either on, off or inverted from on to off (or vice versa) in a single bitwise to confuse your usersoperation. You have the ability to apply black&white or grayscale images as masks, leading to semi-transparency or absolute transparency of the image the mask isbeing applied to.PhilosophyAt AcmeCompany we’ve been discussing the idea of accessing acme data via APIs inside Acme and with some of our community for a while. In theory it’s easy to do– in fact we already have an API working together with access via OAuth which we are using for testing internally at AcmeCompany.However there are 3 things we want to get right before we open up access to our community to use the API: 1. 2. 3. If you *do* need We want to make sure that we’ve addressed all the privacy concerns with allowing 3rd parties to access some or all of this data. And we want to be sure that the Terms & Conditions protect the users data from being misused. We want to give out some example code We want to make sure our documentation is good examples, put the mostI’ve said “privacy concerns” so I expect some of you are worried straight away so I’ll expand on this and give a couple examples:Requirements complex cases firstThe Imagine library has the following requirements: • PHP 5.3+Depending on the chosen Image implementation, you may need one of the following: • GD2
  • My Awesome LibraryImage manipulation library for PHP 5.3 inspired by Pythons PIL and other image libraries.Basic PrinciplesThe main purpose of Imagine is to provide all the necessary functionality to bring all native low level image processing libraries in PHP to the same simple and Theory first: It’s importantintuitive OO API. Several things are necessary to accomplish that such as image manipulation tools (resize, crop, etc). There is always a drawing API, which is animportant object-oriented way for creating basic shapes and advanced charts. You can also write text on an image while still being abstracted away from.When you talk about image manipulation, you should also talk about masking functionality and the theories behind it. In computer science, a mask is data that isused for bitwise operations. Using a mask, multiple bits in a byte, nibble, word can be set either on, off or inverted from on to off (or vice versa) in a single bitwise to confuse your usersoperation. You have the ability to apply black&white or grayscale images as masks, leading to semi-transparency or absolute transparency of the image the mask isbeing applied to.PhilosophyAt AcmeCompany we’ve been discussing the idea of accessing acme data via APIs inside Acme and with some of our community for a while. In theory it’s easy to do– in fact we already have an API working together with access via OAuth which we are using for testing internally at AcmeCompany.However there are 3 things we want to get right before we open up access to our community to use the API: 1. 2. 3. If you *do* need We want to make sure that we’ve addressed all the privacy concerns with allowing 3rd parties to access some or all of this data. And we want to be sure that the Terms & Conditions protect the users data from being misused. We want to give out some example code We want to make sure our documentation is good examples, put the mostI’ve said “privacy concerns” so I expect some of you are worried straight away so I’ll expand on this and give a couple examples:Requirements Or else... complex cases firstThe Imagine library has the following requirements: • PHP 5.3+Depending on the chosen Image implementation, you may need one of the following: • GD2
  • Expert Tip #4Stay the hell away from Github Even though your project is open source, your users should keep their filthy hands off of your docs!
  • Expert Tip #5 Include lot’s ofunnecessary information
  • The following options are available: * length * required
  • ardThe following options are available: rw * length aigh tfo tr oS * required To
  • ard The following options are available: rw * length aigh tfo tr oS * required ToThe library can be easily customized throughseveral different options, each which allows you todirect the internal behavior of the object. This isdone so that you can control over the mostcommon options without needing to subclass theobject itself. If you’d like to suggest new options,you can do so by creating the feature and send apatch. In the next section, we’ll talk about theoptions that are available.
  • ard The following options are available: rw * length aigh tfo tr oS * required ToThe library can be easily customized throughseveral different options, each which allows you todirect the internal behavior of the object. This isdone so that you can control over the mostcommon options without needing to subclass theobject itself. If you’d like to suggest new options,you can do so by creating the feature and send apatch. In the next section, we’ll talk about theoptions that are available.
  • Thanks! Ryan Weaver @weaverryanwww.knplabs.com
  • Thanks! Questions? Ryan Weaver @weaverryanwww.knplabs.com
  • Thanks! Questions?Too bad - RTFM :) Ryan Weaver @weaverryanwww.knplabs.com