Upload
ryan-weaver
View
3.155
Download
0
Embed Size (px)
Citation preview
5 Easy Ways to Revolutionize your Open Source Project by Writing
Terrible Documentation
Ryan Weaver@weaverryan
Who is this dude?
http://www.knplabs.com/enhttp://www.twitter.com/weaverryanhttp://www.github.com/weaverryan
Who is this dude?
• Co-author of the Symfony2 Documentation
http://www.knplabs.com/enhttp://www.twitter.com/weaverryanhttp://www.github.com/weaverryan
Who is this dude?
• Co-author of the Symfony2 Documentation
• Core Symfony2 contributor
http://www.knplabs.com/enhttp://www.twitter.com/weaverryanhttp://www.github.com/weaverryan
Who is this dude?
• Co-author of the Symfony2 Documentation
• Core Symfony2 contributor
• CEO KnpLabs US
http://www.knplabs.com/enhttp://www.twitter.com/weaverryanhttp://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/enhttp://www.twitter.com/weaverryanhttp://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/enhttp://www.twitter.com/weaverryanhttp://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/enhttp://www.twitter.com/weaverryanhttp://www.github.com/weaverryan
If you like the presentation,she gets the iPad :)
Act 1:
Why good documentation is the worst thing since “goto”
Good documentation makes your users weak-minded
FU Good Docs
Put your suit and tie on and join us in the penthouse
Put your suit and tie on and join us in the penthouse
Enterprise Businesses LOVE Shitty Documentation
Hippies
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?
Don’t write *any* Documentation
Expert Tip #1
Why no docs?
Why no docs?
• You’re a genius - your time should be spent writing the code only
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?
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?
static function load($class){ if (strtolower(substr($class, 0, 6)) !== 'pear2\\') { return false; } $file = str_replace(array('_', '\\'), DIRECTORY_SEPARATOR, $class) . '.php'; foreach (self::$paths as $path) { if (file_exists($path . DIRECTORY_SEPARATOR . $file)) { require $path . DIRECTORY_SEPARATOR . $file; if (!class_exists($class, false) && !interface_exists($class, false)) { die(new \Exception('Class ' . $class . ' was not present in ' . $path . DIRECTORY_SEPARATOR . $file . '") [PEAR2_Autoload-0.2.3]')); } return true; } }
// ...}
OMFG your code is awesome!
*Never* proofread your Documentation
Expert Tip #2
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”
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)
Perfection on the first try
• Smart guys/gals like you don’t make mistakes, so get back to coding bro!
• 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
• 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...
• 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...
• 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
• 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... I cry during
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 during romantic
comedies... I cry during
romantic comediesLet’s use his
library for our big expensive project!
Theory over Practice
Expert Tip #3
PhD Program in YourLib
PhD Program in YourLibGuess What? Your users aren’t using your library to solve their business problems
PhD Program in YourLibGuess What? Your users aren’t using your library to solve their business problems
What they really want is:
PhD Program in YourLibGuess 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
PhD Program in YourLibGuess 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
PhD Program in YourLibGuess 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
PhD Program in YourLibGuess 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
KEWL - Let’s see it!!!
Example: WAY Too Easy
<?phpuse Imagine\Image\Box;use Imagine\Image\Point;
$imagine = new Imagine\Imagick\Imagine();$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');
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:
Example: WAY Too Easy
<?phpuse Imagine\Image\Box;use Imagine\Image\Point;
$imagine = new Imagine\Imagick\Imagine();$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');
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:
My Awesome LibraryImage 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 code3. 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
My Awesome LibraryImage 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 code3. 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
Theory first: It’s important to confuse your users
My Awesome LibraryImage 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 code3. 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
Theory first: It’s important to confuse your users
If you *do* need examples, put the most
complex cases first
My Awesome LibraryImage 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 code3. 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
Theory first: It’s important to confuse your users
If you *do* need examples, put the most
complex cases firstOr else...
Stay the hell away from Github
Expert Tip #4
Even though your project is open source, your users should keep their
filthy hands off of your docs!
Include lot’s of unnecessary information
Expert Tip #5
The following options are available: * length * required
The following options are available: * length * requiredToo Straig
htforward
The following options are available: * length * required
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.
Too Straightforward
The following options are available: * length * required
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.
Too Straightforward
Thanks!
Ryan Weaver@weaverryan
www.knplabs.com
Questions?
Thanks!
Ryan Weaver@weaverryan
www.knplabs.com
Questions?Too bad - RTFM :)