PYCon Tutorial

How to document an open source Project ?

<tarek@ziade.org>

How am I ?

What are the goals of this tutorial ?

How this tutorial is organized ?

  • a few slides
  • exercises you do.

The plan

A few definitions

What kind of documentation are we talking about ?

A few definitions

Technical documentation that helps to understand how a codebase works and how it can be used.

This can be:

A few definitions

What is the use and who is the target ?

A few definitions

Part 1

Part 1 - Writing a document

This part is composed of three sections:

Mastering reSTructuredText

reSTructuredText is

Mastering reSTructuredText

Mastering reSTructuredText

smile let's do exercise #1 and #2

Mastering reSTructuredText

reST can be:

Python developers love reST

Writing techniques and tips

The seven laws for technical writing:

The Two-step writing process

Writing should be done in two stages (Elbow, 1980):

Each stage should take 50% of the time.

important Split you writing time in two phases, no one can write it right the first time (except Mozart)

Simple style

Targeted readership

Focus on your target when you write a document (Rüping, 2003).

Assume their background knowledge to restrict the scope of the documentation.

important A prerequest section can help a lot.

Focused information

A document is about a clear focus.

A precise title for each section and the document itself, and a summary can help.

important If you cannot easily name the document or one of its section, there's a problem

Realistic examples

Drop the foo and bar habits. Examples must be real-life examples:

Neh:

>>> from package import graph
>>> foo = graph.calculateSquare(1, 1, 1, 1)
>>> bar = graph.renderSquare(foo)

Better:

>>> from package import graph
>>> square = graph.calculateSquare(1, 7, 1, 10)
>>> square_view = graph.renderSquare(square)

"Light but sufficient" approach

A working software is more important than the best documentation in the world (Ambler, 2002).

Quality over Quantity is the best rule.

important Spending too much time to find something in the documentation is a bad sign.

important Think documents like code. Always limit the size of its sections, examples, etc.

wink Modularized documentation is the key.

Structured documents

Use a clear document portfolio to facilitate the reading. Document should use:

important Never write a document that doesn't have a template

Writing techniques and tips

Distribution of tipsheet, let's do exercise #3, and apply the laws smile

Team writing

Pair-writing ensures:

important The best pair is made with the end-user

important Each document should have a champion, though.

Team writing

Let's do exercise #4 to feel it glasses

Topic ideas:

  • cooking recipe
  • how to play a board or card game
  • how to fish shrimps

Writing a document

Conclusions for Part 1:

Pause

Sleeper

Developer that does not practice documentation

Pause

Winner

Developer that write documentation (=winner)

Part 2

Part 2 - Writing documents in Python

This part specializes the documenting process to Python software

Writing documents in Python

Python projects are organized into:

Documenting code

The code is documented with:

Inline comments

Functions, classes and modules

important read PEP8 and PEP256

Documenting modules

Documenting a package

A package comes with a few mandatory files:

Documenting a package

A package comes with a few mandatory folders:

Documenting a package

Let's add mandatory files to pycommunity (exercise #6)

Using documents for Test-Driven Development (TDD)

Using documents for TDD

Let's call it DDD (Documentation-Driven Development)

Why should you use DDD ? smile

Using documents for TDD

How is managed documentation in projects, most of the time ?

Using documents for TDD

Sleeper

Using documents for TDD

sad fast obsolescence of documentation

sad you need to fight with developers so they write doc

sad your project website is always obsolete

Using documents for TDD

What brings DDD to projects ?

Using documents for TDD

Sleeper

(fruit may vary depending on the season)

Using documents for TDD

smile A big part of the documentation is growing together with code

smile developers use documentation to write code (and they love it)

smile your project website upgrades can be partly automated

Doctesting

Let's doctest

Doctesting

important A doctest is still a document: do not drawn it with test fixtures

important The doctest shows usage examples of the public code

important The unit tests tests everything else

wink Keep your doctests code blocks short and simple

Doctesting

glasses Let's practice with exercise #8

Writing documents in Python

Conclusion for Part 2:

Pause

"Doctests are so cool" -- Magnum

"Doctests are so cool" -- Magnum

Part 3

Part 3 - Writing document for Python Projects

This part is composed of four sections:

Writing document for Python Projects

Tutorial

A tutorial is a very high-level document that explains a functionality of a bundle, how to use it or to change it.

Tutorial

A tutorial...

Tutorial

Possible template:

Tutorial

glasses let's do exercise 9

Recipes

Recipes

Examples:

Recipes

Possible template:

Recipes

Let's do exercice 10: "How to use ConfigParser"

Glossary

A glossary builds a shared knowledge by helping to..

Glossary

important If I remove all terms founded in the glossary from tutorials, they should be made of plain english.

Linking everything

PyCommunity

A tool that:

PyCommunity

smile let's try it #exercise 11

Conclusions

The end

References

Useful books:

Useful websites:

Incoming Events

You all go to Rupy in Poznan, Polan, 14/15 April wink