In addition to getting bogged down by the issues with maintaining existing documentation and creating new documentation, I found myself really overwhelmed by a far too exhaustive software development methodology (something I inherited from the original project team.) I felt stuck in the mud, focused on the methodology and creating the deliverables as per the methodology, instead of creating documentation.
At some point, I discovered at the local bookstore "Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process", by Scott Ambler.
Before the book, I already knew that the methodology and deliverable templates at hand weren't working for me, yet I kept banging my head against the wall trying to make them work. After the book? I felt like I could toss aside what didn't work and I felt free to explore an approach that fits me.
Since then and to this day, I keep in mind and refer to Scott Ambler's "Agile Modeling" and (even more so) Scott Ambler's:
With permission from the author, here are some of Scott Ambler's agile and lean philosophies (towards documentation) which I find particularly useful to Intertwingularity Mapping:
The fundamental issue is communication, not documentation.
Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
Travel as light as you possibly can.
The benefit of having documentation must be greater than the cost of creating and maintaining it.
Create documentation only when you need it.
Update documentation only when it hurts.
Agile documents are "lean and sufficient".
Agile documents fulfill a purpose.
Agile documents describe "good things to know".
Agile documents are sufficiently accurate, consistent, and detailed.
Keep documentation just simple enough, but not too simple.
Write the fewest documents with least overlap.
Put the information in the most appropriate place.
Display information publicly.
Document with a purpose.
Focus on the needs of the actual customers(s) of the document.
Iterate, iterate, iterate (evolutionary approach: incremental).
Start with models you actually keep current.
And from Agile Modeling:
- Single Source Information
- Document Late
- Document Continuously
- Multiple Models
- Just Barely Good Enough
As I slowly piece together a comprehensive explanation of "Intertwingularity Mapping", you'll find deeply intertwingled influences of Scott Ambler's writings (about Agile Modeling and about Agile/Lean Documentation).
On that cheers !
No comments:
Post a Comment