[Pycon] [new paper] "Daniele Procida" - Documentation in practice

[info a pycon.it]

Title: Documentation in practice
Duration: 45 (includes Q&A)
Q&A Session: 0
Language: it
Type: Talk

Abstract: At [Divio][1], I have developed a [documentation system][2] that has been widely presented (in talks and workshops) and adopted by other organisations and in other projects.

![][3]

As a system for thinking about and structuring documentation, it solves many problems that maintainers face, bringing clarity and simplicity to untidy and complex material.

The real world however is in fact untidy, complex and full of irritating edge-cases, that often seem to resist being placed into neat and tidy structures. How well does the system cope with this? What can be done when it appears that the material fits the structure poorly? How can we minimise the extra work we will inevitably create for ourselves when we make wrong decisions that we need to correct later (something that happens in all kinds of projects)?

Using examples, I will discuss challenges and limitations that have arisen in practice, and ways I have found to tackle them. Experience in our own documentation shows that similar issues tend to arise repeatedly, and if they can't all be solved perfectly neatly, they can at least be managed satisfactorily and pragmatically

  [1]: http://www.divio.com
  [2]: https://www.divio.com/blog/documentation/
  [3]: https://www.dropbox.com/s/y1z46zzlf8691sa/documentation.png?raw=1


Tags: [u'documentation']