Upgrade to Pro — share decks privately, control downloads, hide ads and more …

If code is poetry, then documentation is prose

If code is poetry, then documentation is prose

Yes, code might be poetry, showing the elegance of the verses, rhythm, expressiveness; but without good documentation that explains what it does, you will likely end up with unsatisfied users or no users at all.

If anyone had told me I would have spent more time writing documentation than coding, I would not have believed it, but that was before I discovered a simple but powerful law: “more documentation, more users, more contributors”.

During the talk we will see which are the foundations of good documentation and how documentation can let your open source project take off.

Massimiliano Pippi

May 24, 2014
Tweet

More Decks by Massimiliano Pippi

Other Decks in Programming

Transcript

  1. If code is
    poetry,
    then
    documentation
    is prose

    View Slide

  2. Hi
    I'm Massimiliano Pippi,
    Software Developer, Python Lover, Dad.
    dev.pippi.im :: @maxpippi :: github.com/masci
    working @
    evonove.it

    View Slide

  3. what is POETRY?
    Verse: a sequence of words in a single line
    Rhyme: equality of the sound of different
    words
    Stanza: a group of verses

    View Slide

  4. poetry in action
    E’ l’alba: si chiudono i petali
    un poco gualciti: si cova,
    dentro l’urna molle e segreta,
    non so che felicità nuova.
    Il Gelsomino notturno, G.Pascoli
    or, in english:
    Night Blooming Jasmine, by G.Pascoli
    It’s dawn: the petals, slightly worn,
    close up again—each bud to brood,
    in its soft, secret urn,
    on some yet-nameless good.

    View Slide

  5. Poetry in action?
    Critical section, anonymous
    lock = threading.lock()
    lock.acquire()
    try:
    print(“Let’s get critical”)
    finally:
    lock.release()
    Critical section, a fancier anonymous
    lock = threading.lock()
    with lock:
    print(“Let’s get critical”)

    View Slide

  6. What's wrong with poetry?
    Poetry, do you speak it?
    Da un immoto fragor di carrïaggi
    ferrei, moventi verso l’infinito
    tra schiocchi acuti e fremiti selvaggi…
    un silenzio improvviso. Ero guarito.
    Ultimo Sogno, G.Pascoli
    or, in english:
    Last Dream, by G.Pascoli
    WAT?
    Out of a motionless infernal
    shudder and clang of steel on steel
    as wagons moved toward the eternal,
    a sudden silence: I was healed.

    View Slide

  7. Wait, just give me a sec...
    WHAT'S WRONG WITH
    POETRY?
    from itertools import chain, islice
    def chunks(iterable, size, format=iter):
    it = iter(iterable)
    while True:
    yield format(chain((it.next(),), islice(it, size - 1)))
    No, really, see what's wrong?

    View Slide

  8. HERE COMES THE PROSE
    Prose is horizontal, Poetry is vertical.
    (E. Montale)

    View Slide

  9. why devs dont write prose
    Problem n.1: quantity
    often more docs than code
    tutorials, screenshots, articles, advertising, ml
    time (and life) consuming
    Problem n.2: quality
    coding is more fun
    write as non native english speaker
    readers are likely non native english speakers
    argument with strangers on the internet

    View Slide

  10. why devs should write prose
    Poets dig into your code but humans read
    documentation first.
    More humans, more users.
    More users, more contributors.
    More contributors, less work for me :)

    View Slide

  11. be good at writing prose
    Code already in place? Work hard as hell.
    Project not yet started? Use Documentation Driven
    Development and if you can't document it, maybe it's
    not a good idea.

    View Slide

  12. LESSON LEARNT
    Write docstrings for your and your team’s mental
    health.
    Write good docs and make them available on the
    internet.
    Write tutorials, a lot of tutorials.
    Write articles, show people how to use your code.
    Listen to your users, there are no stupid questions, only
    stupid developers not answering.

    View Slide

  13. Questions?
    Thanks for your attention :)
    @maxpippi
    http://github.com/masci
    http://dev.pippi.im

    View Slide