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

Daniele Procida - Documentation-driven developm...

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. 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)
  2. 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
  3. 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.
  4. 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.
  5. 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
  6. 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
  7. DEVELOPING PROGRAMMERS DOCUMENTATION ▸ represents an easy way in for

    new contributors ▸ is almost always welcome ▸ raises its author’s of understanding to new levels
  8. 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.
  9. 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.
  10. DOCUMENTATION-DRIVEN DEVELOPMENT - LESSONS FROM THE DJANGO PROJECT DANIELE PROCIDA

    [email protected] ▸ EvilDMP on IRC, GitHub, Twitter etc ▸ Visit the django CMS booth