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
2. Hi I'm Massimiliano Pippi, Software Developer, Python Lover, Dad. dev.pippi.im :: @maxpippi :: github.com/masci working @ evonove.it
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
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.
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”)
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.
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?
8. HERE COMES THE PROSE Prose is horizontal, Poetry is vertical. (E. Montale)
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
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 :)
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.
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.
13. Questions? Thanks for your attention :) @maxpippi http://github.com/masci http://dev.pippi.im