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

Documentation-driven development

Documentation-driven development

Lessons from the Django project - how documentation improves code, community and programmers.

Daniele Procida

May 31, 2016
Tweet

More Decks by Daniele Procida

Other Decks in Technology

Transcript

  1. DOCUMENTATION-DRIVEN
    DEVELOPMENT
    DANIELE PROCIDA

    View full-size slide

  2. ALL ABOUT ME
    DANIELE PROCIDA
    ▸ Community & documentation manager, Divio
    ▸ Board member, Django Software Foundation
    ▸ Django core developer
    ▸ django CMS developer
    [email protected]
    ▸ EvilDMP (IRC, GitHub, Twitter)

    View full-size slide

  3. DOCUMENTATION-
    DRIVEN DEVELOPMENT

    View full-size slide

  4. DON’T DOCUMENT YOUR CODE, CODE YOUR DOCUMENTATION
    DOCUMENTATION-DRIVEN DEVELOPMENT
    ▸ like test-driven development, puts should before is
    ▸ establishes a shared, easily-accessible, higher-level
    overview of the work
    ▸ provides a shared, easily-accessible metric of success
    ▸ encourages contribution and engagement of non-
    programmers
    ▸ binds programming effort into a coherent narrative

    View full-size slide

  5. LESSONS FROM THE DJANGO
    PROJECT
    DOCUMENTATION-DRIVEN DEVELOPMENT

    View full-size slide

  6. DJANGO’S
    DOCUMENTATION IS
    EXEMPLARY

    View full-size slide

  7. DJANGO’S DOCUMENTATION IS EXEMPLARY
    WHAT’S SO GOOD ABOUT IT?
    ▸ It’s structured properly (tutorials, how-to, reference, topics).
    ▸ Within that structure, it’s clear and consistent.
    ▸ It covers just about everything.
    ▸ It’s held to the highest standards.
    ▸ It exemplifies important values (clarity, courtesy,
    friendliness)
    ▸ Documentation in Django is a process, not just a product.

    View full-size slide

  8. DJANGO’S DOCUMENTATION IS EXEMPLARY
    WHAT DIFFERENCE DOES THIS MAKE?
    ▸ It makes Django easier to learn and adopt.
    ▸ It makes people better Django programmers.
    ▸ It lowers the support burden.
    ▸ It makes the development of Django itself easier and
    faster.

    View full-size slide

  9. DJANGO’S GOOD
    DOCUMENTATION IS GOOD
    FOR DJANGO

    View full-size slide

  10. SOFTWARE IS NOT THE
    ONLY THING THAT
    DEVELOPS

    View full-size slide

  11. WHAT DOES DOCUMENTATION MEAN
    FOR THE DEVELOPMENT OF
    COMMUNITIES AND
    PROGRAMMERS?

    View full-size slide

  12. DEVELOPING A
    COMMUNITY

    View full-size slide

  13. DEVELOPING A COMMUNITY
    DJANGO’S DOCUMENTATION
    ▸ represents its attitudes
    ▸ is an implicit contract with its community
    ▸ is a commitment to standards of communication and
    information
    ▸ is treated as an activity, not just as content

    View full-size slide

  14. RTFM
    Unsympathetic programmers
    DEVELOPING A COMMUNITY

    View full-size slide

  15. INFORMATION AND
    DOCUMENTATION AS
    PRODUCT AND CONTENT

    View full-size slide

  16. INFORMATION AND
    DOCUMENTATION AS
    PROCESS AND ACTIVITY

    View full-size slide

  17. DEVELOPING A COMMUNITY
    INFORMATION AS COMMUNICATIVE TRANSACTIONS BETWEEN AGENTS
    ▸ clarity
    ▸ intelligibility
    ▸ relevance
    ▸ comprehension
    ▸ attention to the needs and abilities of the other party
    ▸ affirmation of mutual understanding

    View full-size slide

  18. GOOD DOCUMENTATION
    SHOWS RESPECT

    View full-size slide

  19. DJANGO’S
    DOCUMENTATION INFORMS
    ITS COMMUNITY

    View full-size slide

  20. DEVELOPING
    PROGRAMMERS

    View full-size slide

  21. DEVELOPING PROGRAMMERS
    DOCUMENTATION
    ▸ represents an easy way in for new contributors
    ▸ is almost always welcome
    ▸ raises its author’s of understanding to new levels

    View full-size slide

  22. DJANGO’S DOCUMENTATION
    STRUCTURE GUIDES NEW
    CONTRIBUTIONS

    View full-size slide

  23. CONTRIBUTIONS TO DJANGO’S
    DOCUMENTATION ARE TAKEN
    SERIOUSLY AND HELD TO THE
    HIGHEST STANDARDS

    View full-size slide

  24. CONTRIBUTIONS TO
    DJANGO’S DOCUMENTATION
    ARE VALUED

    View full-size slide

  25. DOCUMENTING CODE IS
    THE BEST POSSIBLE WAY
    TO UNDERSTAND IT

    View full-size slide

  26. DJANGO’S DOCUMENTATION
    ADVANCES THOSE WHO
    CONTRIBUTE TO IT

    View full-size slide

  27. DJANGO DOES
    DOCUMENTATION-DRIVEN
    DEVELOPMENT

    View full-size slide

  28. WHAT CAN YOUR
    PROJECT DO?

    View full-size slide

  29. WHAT CAN YOUR PROJECT DO?
    PRACTICAL STEPS
    ▸ Structure your documentation correctly (tutorials, how-to,
    reference, topics).
    ▸ Make your documentation policies as rigorous as your
    code policies.
    ▸ Document your documentation.
    ▸ Value your documentation contributors.
    ▸ Value the activity of documentation and information.

    View full-size slide

  30. WHAT CAN YOU OR YOUR ORGANISATION DO?
    PRACTICAL STEPS
    ▸ Attend a Write the Docs
    conference or workshop -
    writethedocs.org.
    ▸ Make being a Documentation
    manager part of someone’s role.
    ▸ Spend money and time on
    documentation.

    View full-size slide

  31. DOCUMENTATION IS
    BECOMING A MOVEMENT

    View full-size slide

  32. ANY QUESTIONS?
    THANK YOU

    View full-size slide

  33. DOCUMENTATION-DRIVEN DEVELOPMENT - LESSONS FROM THE DJANGO PROJECT
    DANIELE PROCIDA
    [email protected]
    ▸ EvilDMP on IRC, GitHub, Twitter etc
    ▸ Visit the django CMS booth

    View full-size slide