5 tips for writing terrible documentation

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

http://www.knplabs.com/en


http://www.twitter.com/weaverryan


Who is this dude?

• Co-author of the Symfony2 Documentation






Who is this dude?


• Core Symfony2 contributor






Who is this dude?



• CEO KnpLabs US






Who is this dude?



• CEO KnpLabs US

• Boyfriend of the much more talented @leannapelham






Who is this dude?



• CEO KnpLabs US

• Boyfriend of the much more talented @leannapelham


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?

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?


• Your code is the most beautiful code ever written - why deprive your users of needing to look through it?

Why no docs?


• 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”


“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)


• 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





comedies... I cry during

romantic comedies





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


What they really want is:



* an extensive lecture of the theory behind your software



* an extensive lecture of the theory behind your software * code-examples that are absent or - at the very least - ridiculously difficult to find



* 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



* 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:

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


Basic Principles



Philosophy






Requirements


• PHP 5.3+


• GD2

Theory first: It’s important to confuse your users


Basic Principles



Philosophy






Requirements


• PHP 5.3+


• GD2


If you *do* need examples, put the most

complex cases first


Basic Principles



Philosophy






Requirements


• PHP 5.3+


• GD2


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

Thanks!


www.knplabs.com

http://www.knplabs.com


Thanks!


www.knplabs.com

Questions?



Thanks!


www.knplabs.com

Questions?Too bad - RTFM :)



5 tips for writing terrible documentation

Technology