Talk in English - US at DomCode - May 2017
View Slides: https://www.slideshare.net/matthiasnoback/living-documentation-presentation
Short URL: https://joind.in/talk/6f010
(QR-Code (opens in new window))
“Documentation”, a word that makes developers yawn. It’s what you write because you have to. Documentation is a failure by definition. You know it, it’s true. Writing it is going to be a tiresome, mindnumbing exercise. Documentation is going to be incomplete, outdated, unreliable and soon to be abandoned anyway. Why would you ever start working on it in the first place?
That’s why we were happy when we discovered the Agile Manifesto, which says: “Working software over comprehensive documentation” That’s a good reason to drop all our documentation efforts, right? Well, no. We shouldn’t quit writing docs. We should simply prevent documentation from being an impediment to other prominent Agile values, like “Responding to change”.
In this talk, I’ll cover the Principles of Living Documentation. I’ll show you many ways to make your documentation activities effortless and more fun. Your docs will never be outdated anymore, everything will be version-controlled, automatically built and ready to share with anyone who’s interested. Any day, any time.
Comments
Comments are closed.
Excellent talk, well presented. Didn't agree with everything, but all the better: it's great to hear a well-presented point that conflicts with your own views.
The main thing that could perfect this presentation would IMHO be to explain somewhere in the first part of the presentation what *kind* of documentation you're talking about and/or what your definition would be. E.g. some things that weren't (entirely or timely) clear to me:
- Is user documentation (e.g. manuals) included?
- Is mandatory documentation (e.g. required by law) included?
- Are we just talking about docs for public APIs / endpoints / touch points, or also inline comments?
Three other final random points I missed:
- Is there a difference between Line-of-Business applications and APIs or Frameworks?
- Does the (intended) audience of the docs matter?
- I also would've loved to have seen a quick toy project with what would be considered "perfect", documentation wise.
But again, all in all: good talk!
I liked the structure of the presentation. First a few examples what the possibilities are, explain why the most of these methods are not optimal and eventually share the better ways to document your code.
It was good to hear my colleagues and I are documenting our code in a good way. It's always nice to get confirmation.
If you ever come across a script which can automatically built a documentation website based on code in a version-controlled repository, let me know!
This talk was smooth. Well-paced, decent slides, voice wasn't too quiet (but could have been louder in that echo-y hall).