Software Documentation in an Agile Environment NERD Summit 2017
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
Software Documentation in an Agile Environment
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
What’s the same? Software Documentation in an Agile Environment
Software Documentation in an Agile Environment
We write for the one person in the office who reads this stuff. Software Documentation in an Agile Environment
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
What’s different? Software Documentation in an Agile Environment
Agile has become a “thing” 2016 Technical Communication Benchmarking Survey Software Documentation in an Agile Environment
An oxymoron in the making Software Documentation in an Agile Environment
One board to rule them all (x 5) Software Documentation in an Agile Environment
Documentation as code h/t Tom Johnson – I’d rather be writing. Software Documentation in an Agile Environment
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
Planning as a team sport Software Documentation in an Agile Environment
“Do you get enough time?” Software Documentation in an Agile Environment
“Done” vs. “Done-Done” Software Documentation in an Agile Environment
Tools Software Documentation in an Agile Environment
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
Choose your tools wisely Software Documentation in an Agile Environment
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
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
About DITA XML Topics with specialization Scales only upward Concept Reference Task Scales only upward http://dita.xml.org Software Documentation in an Agile Environment
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
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
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
What’s next? Software Documentation in an Agile Environment
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
Agile, RUP, and techdoc Agile And Technical Writing by Tara Charter Software Documentation in an Agile Environment
Software Documentation in an Agile Environment
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
Agile things Sprints Stories Confidence votes Stand-ups Burndown Velocity Software Documentation in an Agile Environment
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
DITA for the impatient Source: http://www.xmlmind.com/tutorials/DITA/#task_element Software Documentation in an Agile Environment
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