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.

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