On the wiki, we can constantly keep product documentation updated based on the latest Product Technical Fixes (PTFs), hopefully doing away with the need for separate Product Documentation Changes (PDCs). But how can you be sure that the wiki has been updated to reflect major PTFs? Critically, how do you know if your exported PDFs and EPUBs are up to date in disaster recovery scenarios where you cannot connect to the Internet or even your intranet--when Murphy's Law hits, as one of you put it?
In this discussion, I'll put up the default features of our wiki that pertain to this, and suggest some processes that we tech writers can implement to improve this situation. Please comment and make your own suggestions.
Existing mechanisms
- Watch notifications. The wiki is set up with a watch mechanism to notify you of changes by email, if you opt in to this service. By default, these notifications include diffs, so you should quickly be able to tell whether an update addressed a particular PTF or was just a typo fix or format improvement. However, this does not directly address the issue of ensuring that documentation exported from the wiki is current. Perhaps these notifications would be most helpful if you regenerated PDFs and EPUBs based on them? We would also have to generate new HTML exports for those of you who keep such exports on your secure intranet.
- Dates on PDF cover pages. These are only available on PDFs generated using the Book output option. And they only indicate the date that the PDF was created. However, a PDF created from the wiki will necessarily include all updates to the wiki up to that date. If you have watch notifications enabled, you should be able to compare that date to the date of the last major wiki update and know whether the PDF is up to date. Admittedly, this is neither optimally convenient nor optimally reliable: What about EPUB? What if you don't remember the date of the last PTF or wiki update, and you cannot access the notification emails?
- Page history. You can check the history of a page on the wiki before you use it, to see if there is a change related to the PTF. All changes should have a bit of text describing them, and writers should indicate the number of a PTF when they make a related update. However, this feature is only accessible on the wiki, so is of very limited help in a disaster recovery situation.
Suggested measures
This is not an exhaustive list but simply the results of a VM:Backup beta customer meeting along with my thoughts afterwards. Please feel free to make additional suggestions in the comments. Also, this list should not be considered "either/or".
- "Documentation Changes" pages. A page in Release Notes or About This Documentation that is updated with every post-GA doc change, including links to individual pages. This feature is already in use in some product documentation.
- Announcements and News. On the wiki homepage, an announcement for every significant update due to PTF or major doc bug. This could also include links to individual pages. Currently this section is wiki-only, but it might be possible to include it in exported documentation, too; I will investigate.
- A 'change log' in the text body of changed pages. A Note at the top of every page created or edited due to a major PTF after GA. This cannot be automated but could be included in writer processes. This would let you know the status of a page even if it is physically separate from the rest of the documentation. I would prefer to make this note visible only in exported content (which the wiki allows me to do). I think it would be an unnecessary distraction in the wiki itself, especially if changes are announced on the home page.