From my "Write the Docs" newsletter today:
As documentarians, we sometimes come head-to-head with other stakeholders on what to include in our documentation. One contentious topic is forward-looking statements: some stakeholders might want to tell users that a feature is coming soon. But when we mention a future feature in docs, it can be a problem if that feature doesn’t end up being delivered.
Here are some thoughts about how to approach this from a conversation about roadmaps in documentation this month:
Do you have opinions or advice on this? Head on over to #general!
- Be aware that documentation saying that something will be delivered, or even when it’ll be delivered, can be considered legally binding. You might want to consider a safe harbor statement.
- If your roadmap is in the documentation, who responds to feedback on that roadmap? The doc writer may not be the best person.
- Documentation is likely not the appropriate place to store a roadmap. Product managers should instead consider customer support sites or other publications from the company. Publicizing the roadmap is gaining traction (here’s an article about the idea).
- If the roadmap or future features must exist somewhere in your documentation, release notes can be a good place for them. But consider creating a separate document instead that can be shared with customers - with all of the appropriate disclaimers.
Oh my gosh! This used to drive me BONKERS! I can't count the number of times I was asked to add text to end-user documentation about a feature that was not completely implemented but had been implemented just enough to see something in the user interface - it could have been a widget like a check box or entry field on a window that was disabled or something more hidden like a drop-down option - for a soon-to-be released version of the software with "BIG PLANS" to finish the work on the feature in the NEXT release.
Here's a good example. This page - https://support.assessment.pearson.com/display/TN/10000s+-+Scoring+CAT+Server+Warnings - was last updated by me on Nov 06, 2015 17:52, which was 3 years, 3 months, 3 weeks, 6 days (1215 days) ago. Why does the page need to exist? Because, at the time, it was thought that the Scoring CAT Server Warnings were actually going to be added to the end-user documentation. Thus, the page was created and the placeholder text was added. NO ONE has touched the page since I worked at Pearson and, since I don't work there anymore, I have zero insight into whether the Scoring CAT Server Warnings are actually coming soon or not. <grin>
No comments:
Post a Comment