After every major release, do a post mortem of your technical documentation and look at how you can improve team morale, writing process, document reviews, and the documentation product.
Image may be NSFW.
Clik here to view.
Post-mortems focus on two areas
- Quantitative data — such as, the difference between the project estimate and the hours worked.
- Qualitative data — such as, satisfaction, user satisfaction, quality of deliverables.
Why should you do a post mortem on your technical documents?
It helps you identify:
- What went well
- What should be repeated in future projects
- What could be improved in future projects
- What went wrong and
- What should be avoided in future projects
What prevented you from getting ideal product, such as lack of training, QA/Dev support, lack of time, lack of working software, low-quality feedback, or confusion on our own processes.
To Perform a Post Mortem on Technical Documents
Create a spreadsheet. Add columns for the following:
- Project/Task/Roadmap
- Description
- What Happened
- What worked
- What didn’t work
Recommendations
Common issues during documentation development
Examples might include:
As the CMS wasn’t developed on time, we were unable to write any material.
Recommendation: change scope of documentation plan
Technical Specifications. Better communication of specs, ie less time hunting around for info. More Demos of new product features. Tech specs were not available.
Recommendation: change scope of documentation plan. Specs must be written in English.
Bugs were NOT entered into bug tracking system making it impossible to create release notes.
Recommendation: re-schedule release notes
Time lost using Jira, issue tracking software. Not sure if anyone used the info in other tool.
Recommendation: training
Cross-dept confusion regarding how to update product roadmaps in Jira.
Recommendation: training
Only Bugs and Enhancements were updated, not new features.
Recommendation: schedule time to update guides or prioritize guides over release notes
Team Reviews. Several bugs required reviews from different teams. However, not all testers were aware that bugs affected them resulting in late reviews, changes to text, new pdfs etc.
Recommendation: clarify expectations with QA. Circulate a checklist explaining what is expected of each dept BEFORE roadmaps start.
Reviews & Feedback. Inability to contact Dev teams in Paris etc. Unable to get info, validation etc from dev team in days before release
Recommendation: Advance notice so we can use time better and focus. Better communications on state of release.
Document Release Schedule. Creating content, PDFs, updating content, re-pdfing etc is time consuming, error prone, and demoralizing.
Recommendation: Agree create cutoff point, eg date before release Or Create content to the last minute and create PDFs day after.
Workload. Doc team is in the office until 8,9, or 10 at least one night a week, often on Friday.
Recommendation: agree review cut off date
Bug Status. Bugs are doced when To Be Validated. However, many bugs were later refused, or not tested, which meant they need to be removed from the PDFs. This meant we had to a) recompile PDFs b) perform more sanity checks.
Recommendation: agree review cut off date
Summary
To get the most value from post-mortems, given each writer the responsibility to try and resolve one area. Iron out the main obstacles first as fixing these often solves other issues.