There is a need to let our users edit and annotate documents (PDF, Word) online (think DropBox Paper or Google Docs) in the browser. So there may be a need off the back of that the lets users see how things have changed over time and by who. A version history.
However, in the interim (you know how long these can last :) ) users will be able to view the document online, but not necessarily be able to edit it. So we're going to let them download a version, make edits offline and then upload it again.
Will add to this when I find out more from research.
Dropbox Paper audit
On 14th March 2019 the Design System team reviewed a Dropbox Paper document discussing the document history pattern.
The aim was to reduce the number of places containing guidance and code by:
Below is a record of the outcomes of that review.
If you need to, you can see the original Dropbox Paper content in the internet archive.
Combine the document history discussion on Dropbox Paper with this issue and remove the original Dropbox Paper page.
Help users understand when a document was changed and why.
When to use this pattern
Use this pattern if your users need to know when and why the content in a document was changed. For example if the document contains standards, guidelines or legislation that users have to follow, they need to know if it has changed since they last used it.
How it works
Don’t include minor updates
Only include updates that change the meaning of the content. Don’t include minor updates that only change the format or correct spelling mistakes.
Provide different levels of detail
Different users will want different levels of detail, depending on the way they use your content. Some may just need to know when the document was last updated, some may need a summary of the last update and why it was made, others may need to see every single edit in detail.
Use research to understand your user’s needs and make sure your design supports them.
The example below is from the bottom of a page in the GOV.UK Service Manual. Users are initially just shown a dated summary of the last edit. However there are links to see the edit in detail on a separate page and also to see previous edits:
Example: Service manual
Understanding when and why updates are made
Users are building their services to the specification of the guidance that the service manual provides. It is therefore important that when this guidance is changed or updated we clearly explain what has been changed, and why.
Research has shown that users have varying levels of interest in the updates to guidance, often depending on their role within the service team or the kind of guidance in question. We show two levels of detail:
In-guide summary of updates
We have adapted one of the 'last updated' patterns from GOV.UK to into our page footer. As well as showing a list of the updates with their timestamp, the update summary has also been included.
This gives users enough information to make a discussion to either interrogate the update further and link though to the page update or be satisfied with the information in the description and continue browsing.
The more engaged users can then find out more detail in the 'Page update' page.
These pages document the state of the guidance on the date of the update, including a summary of the change, a detailed description of the reasons for the change and a preview of the actual changes from the previous version.
This stand alone page approach was taken as it allow us to easily surface more contextual information about the change. It should also be more clear to the user that they are not looking at the latest version of the guidance due to the considerably different page layout.
Having explored a wide range of approaches to showing diffs (GitHub, Wikipedia, Google, etc.) and experimented with existing service manual content and updates, we are confident that the in-body comparison is more readable with our style of content and thus more effective than the side-by-side approach.
Still to do
What exactly should be included in the explanation and descriptions of the updated still need to be nailed down. We hope to develop a clear rational for anyone publishing updates to the guidance to ensure the change log is filled out effectively as possible.
Just to say there are HTML tags for identifying ranges of text that have been deleted and inserted into documents:
These were used on Digital Marketplace though I'm not sure this was ever tested with users of assistive technologies to see if they communicated the semantics correctly.