1. Software Documentation in an Agile Environment
NERD Summit 2017

2. About yours truly Karl Hakkarainen – kh@queenlake.com 508 829 5825
35+ years in technical documentation and information technology
My grandchildren still ask me for help with their WiFi networks, phones, and other technology problems.
About yours truly
Software Documentation in an Agile Environment

3. Software Documentation in an Agile Environment

4. No one will tell you that doc isn’t important
Those who believe that it’s important will tell you that it is
Those who don’t believe that it’s important won’t tell you anything
Software Documentation in an Agile Environment

5. What’s the same?
Software Documentation in an Agile Environment

6. Software Documentation in an Agile Environment

7. We write for the one person in the office who reads this stuff.
Software Documentation in an Agile Environment

8. Based on this page, I would not know why I would want to use this
-- My boss
Each user story needs to describe a problem and how we’ve solved it.
Software Documentation in an Agile Environment

9. What’s different?
Software Documentation in an Agile Environment

10. Agile has become a “thing”
2016 Technical Communication Benchmarking Survey
Software Documentation in an Agile Environment

11. An oxymoron in the making
Software Documentation in an Agile Environment

12. One board to rule them all (x 5)
Software Documentation in an Agile Environment

13. Documentation as code h/t Tom Johnson – I’d rather be writing.
Software Documentation in an Agile Environment

14. History tells me that the next sprint will be as interrupt-driven as the past one.
-- My boss
Past performance is a predictor of future results.
Software Documentation in an Agile Environment

15. Planning as a team sport
Software Documentation in an Agile Environment

16. “Do you get enough time?”
Software Documentation in an Agile Environment

17. “Done” vs. “Done-Done”
Software Documentation in an Agile Environment

18. Tools
Software Documentation in an Agile Environment

19. The best shortcut is a trip to the truck to get the right tool for the job.
Anon
What is the best documentation toolset for Agile?
Software Documentation in an Agile Environment

20. Choose your tools wisely
Software Documentation in an Agile Environment

21. Agile tools
Most tools associated with Agile are project- management tools
They don’t help you keep use cases and documentation sources in sync.
Software Documentation in an Agile Environment

22. Documentation tools Darwin Information Technical Architecture (DITA)
Markup languages
MarkDown
reStructured Text …
HATs (Help Authoring Tools)
MadCap Flare
Graphics editors
Illustrator
Photoshop
Open source alternatives
Software Documentation in an Agile Environment

23. About DITA XML Topics with specialization Scales only upward
Concept
Reference
Task
Scales only upward
Software Documentation in an Agile Environment

24. About MarkDown Follows the HTML model
Fail silently
Link to external content
Works great with the GitHub model
A formal spec for GitHub Flavored Markdown
Fails for book publishing
Missing ‘include’ directive
Missing conditionals
Software Documentation in an Agile Environment

25. reStructuredText Plain text Includes features missing in MarkDown
Conditionals – Including content based on tags
Includes - Including an External Document Fragment
Integrated with build environment (Sphinx)
But, …
It’s not MarkDown
Software Documentation in an Agile Environment

26. Books in Agile Tools for modular content New or enhance stories
Plan time and effort for release process
Final editing and sign-off
Electronic distribution
Print production, review, and release
Software Documentation in an Agile Environment

27. What’s next?
Software Documentation in an Agile Environment

28. Process and tools improvements
Making the process repeatable
Integration with build process
Version tracking and Confluence
We can control versioning with release process
We support up to 10 versions of our software
Capturing informal conversations
Improving usefulness
Task-oriented documentation
More code examples
Software Documentation in an Agile Environment

29. Agile, RUP, and techdoc Agile And Technical Writing by Tara Charter
Software Documentation in an Agile Environment

30. Software Documentation in an Agile Environment

31. Notes Log statements as technical documentation
Capturing tribal knowledge
Reverse-engineering a product or feature
Traditional disciplines
Information Architecture
Knowledge Management
Software Documentation in an Agile Environment

32. Agile things Sprints Stories Confidence votes Stand-ups Burndown
Velocity
Software Documentation in an Agile Environment

33. About doc tickets 90% of the tickets are bug fixes
Less than 1% require more than one sprint to complete
Software Documentation in an Agile Environment

34. DITA for the impatient
Source:
Software Documentation in an Agile Environment

35. Your new friends Coding standards Source control Comments
Directory layout
Clean code
Source control
Watch the check-ins
Participate in code reviews
Software Documentation in an Agile Environment