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/

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
   ▸ daniele.procida@divio.com
   ▸ 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
    ▸ daniele.procida@divio.com
    ▸ EvilDMP on IRC, GitHub, Twitter etc
    ▸ Visit the django CMS booth
    

    View Slide