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.

1. 5 Easy Ways to Revolutionize your
Open Source Project by Writing
Terrible Documentation
Ryan Weaver
@weaverryan

2. Who is this dude?
http://www.knplabs.com/en
http://www.twitter.com/weaverryan
http://www.github.com/weaverryan

3. 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

4. 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

5. 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

6. 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

7. 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

8. 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

9. Act 1:
Why good documentation is
the worst thing since “goto”

10. FU Good Docs
Good documentation makes
your users weak-minded

11. Put your suit and tie on and
join us in the penthouse

12. Put your suit and tie on and
join us in the penthouse
Enterprise Businesses LOVE
Shitty Documentation

14. p i e s
H i p

16. Who can I make the
check out to sir?

17. Who can I make the
check out to sir?

18. Who can I make the
check out to sir?

19. Act 2:
I’m sold! But how can *I* write
shitty documentation?

20. Expert Tip #1
Don’t write *any*
Documentation

21. Why no docs?

22. Why no docs?
• You’re a genius - your time should
be spent writing the code only

23. Why no docs?
• You’re a genius - your time should
be spent writing the code only
• Your code is the most beautiful
code ever written - why deprive your
users of needing to look through it?

24. 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?
}
}
// ...
}

25. Expert Tip #2
*Never* proofread your
Documentation

26. Perfection on the first try

27. Perfection on the first try
“Documentation is like a dream - it’s
the raw expression of how you
subconsciously want your application
to work. Proofreading it clouds that
interpretation and abstracts away
from its perfection”

28. Perfection on the first try
“Documentation is like a dream - it’s
the raw expression of how you
subconsciously 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)

30. • Smart guys/gals like you don’t make
mistakes, so get back to coding bro!

31. • 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

32. • 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...

33. • 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...

34. • 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
during romantic
comedies

35. • 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 during
during romantic
romantic comedies
comedies

36. • 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 during
during romantic library for our big
romantic comedies
comedies expensive project!

37. Expert Tip #3
Theory over Practice

38. PhD Program in YourLib

39. PhD Program in YourLib
Guess What? Your users aren’t using your
library to solve their business problems

40. PhD Program in YourLib
Guess What? Your users aren’t using your
library to solve their business problems
What they really want is:

41. PhD Program in YourLib
Guess What? Your users aren’t using your
library to solve their business problems
What they really want is:
* an extensive lecture of the theory behind
your software

42. PhD Program in YourLib
Guess What? Your users aren’t using your
library to solve their business problems
What 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

43. PhD Program in YourLib
Guess What? Your users aren’t using your
library to solve their business problems
What 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

44. PhD Program in YourLib
Guess What? Your users aren’t using your
library 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

45. Example: WAY Too Easy
Imagine is an Image manipulation library for PHP 5.3 inspired by Python's
PIL and other image libraries.
Here’s how you can use it:
<?php
use 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');

46. Example: WAY Too Easy
Imagine is an Image manipulation library for PHP 5.3 inspired by Python's
PIL and other image libraries.
Here’s how you can use it:
<?php
use 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');

47. My Awesome Library
Image manipulation library for PHP 5.3 inspired by Python's PIL and other image libraries.
Basic Principles
The 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
intuitive 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 an
important 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 is
used 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
operation. 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 is
being applied to.
Philosophy
At 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 good
I’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
The Imagine library has the following requirements:
• PHP 5.3+
Depending on the chosen Image implementation, you may need one of the following:
• GD2

48. My Awesome Library
Image manipulation library for PHP 5.3 inspired by Python's PIL and other image libraries.
Basic Principles
The 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
intuitive 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 an
important 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 is
used 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
operation. 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 is
being applied to.
Philosophy
Theory first: It’s important
At 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 users
However 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 good
I’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
The Imagine library has the following requirements:
• PHP 5.3+
Depending on the chosen Image implementation, you may need one of the following:
• GD2

49. My Awesome Library
Image manipulation library for PHP 5.3 inspired by Python's PIL and other image libraries.
Basic Principles
The 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 important
intuitive 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 an
important 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 is
used 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 users
operation. 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 is
being applied to.
Philosophy
At 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 most
I’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 first
The Imagine library has the following requirements:
• PHP 5.3+
Depending on the chosen Image implementation, you may need one of the following:
• GD2

50. My Awesome Library
Image manipulation library for PHP 5.3 inspired by Python's PIL and other image libraries.
Basic Principles
The 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 important
intuitive 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 an
important 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 is
used 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 users
operation. 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 is
being applied to.
Philosophy
At 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 most
I’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 first
The Imagine library has the following requirements:
• PHP 5.3+
Depending on the chosen Image implementation, you may need one of the following:
• GD2

51. Expert Tip #4
Stay the hell away from
Github
Even though your project is open
source, your users should keep their
filthy hands off of your docs!

52. Expert Tip #5
Include lot’s of
unnecessary information

53. The following options are available:
* length
* required

54. ard
The following options are available:
rw
* length aigh tfo
tr
oS
* required
To

55. ard
The following options are available:
rw
* length aigh tfo
tr
oS
* required
To
The library can be easily customized through
several different options, each which allows you to
direct the internal behavior of the object. This is
done so that you can control over the most
common options without needing to subclass the
object itself. If you’d like to suggest new options,
you can do so by creating the feature and send a
patch. In the next section, we’ll talk about the
options that are available.

56. ard
The following options are available:
rw
* length aigh tfo
tr
oS
* required
To
The library can be easily customized through
several different options, each which allows you to
direct the internal behavior of the object. This is
done so that you can control over the most
common options without needing to subclass the
object itself. If you’d like to suggest new options,
you can do so by creating the feature and send a
patch. In the next section, we’ll talk about the
options that are available.

57. Thanks!
Ryan Weaver
@weaverryan
www.knplabs.com

58. Thanks!
Questions?
Ryan Weaver
@weaverryan
www.knplabs.com

59. Thanks!
Questions?
Too bad - RTFM :)
Ryan Weaver
@weaverryan
www.knplabs.com