Last edited 08 Mar 2018

Construction industry knowledge standard

Guidelines for the preparation of knowledge to make it easy to publish, find and use.


This document is a draft for consultation. To suggest changes, you can click 'Add a comment' at the bottom of the page or you can email [email protected]

Contents

[edit] Introduction

Construction is a knowledge-based industry. We disseminate much of our knowledge electronically, sharing it across an array of different software applications, operating systems and devices. However, we generally prepare it as if it is going to be printed, often in pdf format, with all the limitations of hard-copy documents and exploiting few of the inherent benefits of electronic media. This makes knowledge unnecessarily difficult to prepare, publish, find, understand and use.

In the age of digital media, it is important that we prepare knowledge very simply and clearly so we do not inadvertently limit the ways it can be used by others.

This short document provides guidance for the preparation of knowledge to ensure that:

  • It is easier for software to index, so people can find it.
  • It is easier for authors to collaborate in its preparation.
  • It is easier to publish knowledge on different platforms and in different formats without having to reprocess it every time.
  • It is easier for readers to understand.
  • It is properly attributed, and the terms for its use are clear.

[edit] File format

This guide does not place any restrictions on the type of software that can be used to prepare knowledge. If the approach set out in this document is followed, it should be relatively straight forward to transfer content between different applications and operating systems, irrespective of how it was created.

[edit] Accessibility

  • Use plain language titles which enable readers and indexing software to understand the content of the document. Titles should not include symbols (such as / or ?) as they can cause errors in URL's.
  • Summarise useable findings at the beginning. If readers do not find what they are looking for quickly, they will look somewhere else.
  • Explain acronyms when they are first used, but also repeat the full phrase throughout the body of the document as people may start reading it part way through.
  • Only capitalise text when it is absolutely necessary, and then only capitalise the first letter of words. Capitalised text is more difficult to read.
  • Provide links to other sources of information that may help explain concepts that are referred to.
  • Links should include the full URL, ie including the http:// part.

[edit] Design

Documents should be very simple so they can be re-used on different platforms and in different page layouts without needing to be re-processed:

  • Do not use unusual fonts.
  • Do not use coloured fonts or backgrounds.
  • Do not include hard page breaks.
  • Do not format documents into columns.
  • Do not add page numbers.
  • Do not hyphenate long words between lines.
  • Do not include headers or footers.
  • Do not convert words into pictures, for example in title blocks.

[edit] Formatting

Document formatting should be very simple. Complex formatting may not be readable on all platforms:

  • Bulleted and numbered lists should only have one level. Avoid lists within lists.
  • Numbered lists should have simple numbers only. Complex numbering, such as clause numbers should be entered manually.
  • Headings should be applied as proper heading styles, not as formatted normal text. This allows publishers and viewing software to automatically apply their own heading styles and automatically create tables of contents.
  • There should not be more than three levels of headings.
  • Body text should be un-styled or 'normal' style.
  • Spacing between paragraphs should be introduced through paragraph styling (padding above or below the paragraph), not double line breaks.
  • Paragraphs should not be indented or have hanging indents.
  • Tables should not include complex formatting, images or complex cell divisions.
  • Where tables are referred to in the body of the text, the text should refer to the actual table title (or figure number if it has one), rather than using phrases such as 'below', 'left', 'overleaf' and so on.

[edit] Images

  • Image captions should include information about the source of images and any licensing restrictions where these are different to the rest of the document.
  • Image captions should include a plain language title describing the content of the image.
  • Image files should have plain language file names which enable readers and indexing software to understand the content of the image. They should not include symbols as these can cause errors in URL's.
  • Where images are referred to in the body of the text, the text should refer to the actual image title (or figure number if it has one), rather than using phrases such as 'below', 'left', 'overleaf' and so on.

[edit] References

  • References should adopt the Harvard referencing system, with author and date included in the text, and the full references listed alphabetically at the end of the document (not at the end of pages or sections).

[edit] Notes

  • Footnotes should be inserted manually, indicated in the text as numbers in brackets (1), with the footnotes listed at the end of the document. Automated footnote systems may not translate between different software applications.

[edit] Graphs

  • Where graphs are included, the source data should be attached to allow proper interrogation by readers.

[edit] Equations

  • Equations should be written as plain text, or if they are complex, should be inserted as images.

[edit] Time-dependent information

  • Where documents refer to time-dependent information, such as an event which will happen or has recently happened, the text should refer to the actual date rather than using time-dependent phrases such as 'recently', 'soon' or 'will' as these phrases give the document an unnecessary 'expiry' date.

[edit] Complex content

  • Where complex content, such as video is included, it should be uploaded to a suitable platform such as YouTube or Vimeo, and a link provided in the document. Not all software applications are able to show complex embedded content.
  • Captions should include a plain language title describing the content.
  • Captions should include information about the source of the content and any licensing restrictions where these are different to the rest of the document.

[edit] Indexing information

Documents should include indexing information at the beginning:

  • Plain language title.
  • Author details (including organisations and location, and identifying the lead author where there are multiple authors). This may be linked to existing online author profiles, such as Linkedin profiles.
  • Short plain language description.
  • Date of publication (this is very important but often forgotten).
  • Licence restrictions (see below).

[edit] Licence

Documents should adopt licences that reflect the intended purpose of the document. For example, if the purpose for creating a document is the dissemination of knowledge, then adding a copyright symbol that restricts its use may not be the best option.

If it is important that the document must not be copied, shared or altered in any way then it may be appropriate for it to be copyright protected. However, there are a number of freely available Creative Commons licenses that give greater flexibility for use. These can be associated with a document by inserting a link to the relevant license:

  • Attribution: Allows others to distribute, remix, tweak, and build upon the work, even commercially, as long as they credit the author for the original creation.
  • Attribution-NoDerivs: Allows for commercial and non-commercial redistribution, as long as it is passed along unchanged, with credit to the author.
  • Attribution-NonCommercial-ShareAlike: Allows others to remix, tweak, and build upon the work non-commercially, as long as they credit the original author and license their new creations under the identical terms.
  • Attribution-ShareAlike: Allows others to remix, tweak, and build upon the work even for commercial purposes, as long as they credit the original author and license their new creations under identical terms.
  • Attribution-NonCommercial: Allows others to remix, tweak, and build upon the work non-commercially, and although their new works must acknowledge the original author and be non-commercial, they don't have to license their derivative works on the same terms.
  • Attribution-NonCommercial-NoDerivs: Allows others to download the work and share it with others as long as they credit the original author, but they cannot change it in any way or use it commercially.

Comments

To add your thoughts to this discussion page, click 'Add a comment' above.


It has been suggested that the standard should be more prescriptive about the structure of documents. For example, requiring the preparation of an abstract of a certain length.


It has been suggested that the section on images should be expanded to make clear that images should be provided separately at high resolution so that they can be re-sized without loss of quality and so they can be properly indexed and licensed.


Should the standard be developed to include a system for tracking the provenance of knowledge, that is, where did it come from and where else is it used? This might be done by allocating a unique identifier to each piece of knowledge.


Include instructions for how to attach licences to knowledge.


Images need to be provided separately and separately indexed so that they are searchable.


How should very long documents be prepared? Should they be broken into chapters or presented as one very long file? Should a summary be published following a standard format, and linked to the full document?


Linked content (such as the data from which a graph has been created) should be in native or open format.


Images should be provided as image files, not for example as word objects.


Bulleted lists and numbered lists should be properly formatted lists, not normal paragraphs with bullet or number characters at the beginning.


Pull out captions should not be used. It is generally not clear where they fit in the flow of the text.


Images must be part of the flow. Not separated from the text to which they relate, or with text wrapped, or in separate windows.


The use of the future tense in text is limiting. It will become the past.


Be more prescriptive about how to make text accessible to / usable by a wider audience.


Is there a way of making references non-sequential so that sections of content can be re-used without the need to re-number references?


Can it be tailored more to report writing?


Some documents are private, or copyrighted - which licenses are suitable?


Think about what people are looking for rather than what you can publish. Start typing your subject into google and see what it predicts you are looking for.


Is it better to have the subject in the URL as well as the page title?


Is there a way of flagging up / informing the author when a piece of knowledge is no longer current?


Documents should be provided in native format or an open format, rather than as a pdf which is difficult to re-process or use.


Some knowledge is proprietary, and whilst it could be produced following a standard, it would not be accessible or licensed for use by others.


Online content should not be moved as this breaks links to them from other content. If it is necessary to move online content, redirects to the new location should be left behind.


Provenance attributes:

  • Qualifications, status, suitable uses, reliability, disclaimer, current, refereed / certified / checked etc
  • Tag quoted / used content for original provenance.
  • Tag time-dependent info for checking.

Version control makes collaboration easier.


Provide templates


Look at CrossMark system.