$30 off During Our Annual Pro Sale. View Details »

Daniele Procida - Documentation-driven development - lessons from the Django Project

Daniele Procida - Documentation-driven development - lessons from the Django Project

One secret of Django's success is the quality of its documentation. As well as being key to the quality of the code itself, it has helped drive the development of Django as a community project, and even the professional development of programmers who adopt Django.

I'll discuss how Django has achieved it, and how any project can easily win the same benefits.

https://us.pycon.org/2016/schedule/presentation/2089/

PyCon 2016

May 29, 2016
Tweet

More Decks by PyCon 2016

Other Decks in Programming

Transcript

  1. DOCUMENTATION-DRIVEN
    DEVELOPMENT
    DANIELE PROCIDA

    View 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 Slide

  3. DOCUMENTATION-
    DRIVEN DEVELOPMENT

    View 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 Slide

  5. LESSONS FROM THE DJANGO
    PROJECT
    DOCUMENTATION-DRIVEN DEVELOPMENT

    View Slide

  6. DJANGO’S
    DOCUMENTATION IS
    EXEMPLARY

    View 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 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 Slide

  9. DJANGO’S GOOD
    DOCUMENTATION IS GOOD
    FOR DJANGO

    View Slide

  10. SOFTWARE IS NOT THE
    ONLY THING THAT
    DEVELOPS

    View Slide

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

    View Slide

  12. DEVELOPING A
    COMMUNITY

    View 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 Slide

  14. RTFM
    Unsympathetic programmers
    DEVELOPING A COMMUNITY

    View Slide

  15. View Slide

  16. INFORMATION AND
    DOCUMENTATION AS
    PRODUCT AND CONTENT

    View Slide

  17. INFORMATION AND
    DOCUMENTATION AS
    PROCESS AND ACTIVITY

    View Slide

  18. 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 Slide

  19. GOOD DOCUMENTATION
    SHOWS RESPECT

    View Slide

  20. DJANGO’S
    DOCUMENTATION INFORMS
    ITS COMMUNITY

    View Slide

  21. DEVELOPING
    PROGRAMMERS

    View Slide

  22. 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 Slide

  23. DJANGO’S DOCUMENTATION
    STRUCTURE GUIDES NEW
    CONTRIBUTIONS

    View Slide

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

    View Slide

  25. CONTRIBUTIONS TO
    DJANGO’S DOCUMENTATION
    ARE VALUED

    View Slide

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

    View Slide

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

    View Slide

  28. DJANGO DOES
    DOCUMENTATION-DRIVEN
    DEVELOPMENT

    View Slide

  29. WHAT CAN YOUR
    PROJECT DO?

    View Slide

  30. 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 Slide

  31. 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 Slide

  32. DOCUMENTATION IS
    BECOMING A MOVEMENT

    View Slide

  33. ANY QUESTIONS?
    THANK YOU

    View Slide

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

    View Slide