Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document history #19

Open
govuk-design-system opened this issue Jan 12, 2018 · 8 comments
Open

Document history #19

govuk-design-system opened this issue Jan 12, 2018 · 8 comments

Comments

@govuk-design-system
Copy link
Collaborator

@govuk-design-system govuk-design-system commented Jan 12, 2018

AKA: Change note, publication history

What

Show the history of edits to a document.

Why

Used on these services:

@joelanman
Copy link
Member

@joelanman joelanman commented Apr 5, 2018

Removing 'candidate' tag as this doesn't seem to have many examples of usage

@timpaul timpaul added the pattern label May 21, 2018
@adamsilver
Copy link

@adamsilver adamsilver commented Jul 13, 2018

We have a need for this :)

@joelanman
Copy link
Member

@joelanman joelanman commented Jul 13, 2018

@adamsilver cool, can you share more about your users' needs? Have you done any research around it?

@adamsilver
Copy link

@adamsilver adamsilver commented Jul 13, 2018

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.

@conordelahunty
Copy link

@conordelahunty conordelahunty commented Jul 23, 2018

Each GOV.UK Register has a page where it lists when a value has changed. For example, here are all the changes to the country register.

@conordelahunty
Copy link

@conordelahunty conordelahunty commented Jul 23, 2018

Here's how Digital Marketplace shows changes in a contract:

track changes

@soupdragon99
Copy link

@soupdragon99 soupdragon99 commented Mar 14, 2019

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:

  • migrating relevant, useful content into the Design System itself
  • recording important research findings in the community backlog
  • removing the original Dropbox Paper page

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.

Review outcomes

Combine the document history discussion on Dropbox Paper with this issue and remove the original Dropbox Paper page.

Document history

Overview

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:

Here’s the page-update page:
document-history-1

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:

  • a brief summary of the updates, including a one line description of the change (in the metadata at the footer of the guidance.)
  • an in depth view of the specific changes made with more background information (on a separate 'page update' page.)

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.

A page-per-update

The more engaged users can then find out more detail in the 'Page update' page.

document-history-2

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.
The method of displaying the diffs has so far tested well with users showing a strong understanding of the changes being displayed. We are still working on creating a rational for how to write the detail for the change logs.

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.
These update pages will only appear for non-minor (e.g. spelling errors, broken links etc.) updates which will be specified as such in the publishing process.

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.

@tombye
Copy link

@tombye tombye commented Mar 18, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants