Last edited 05 Jul 2016

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 v3 27/10/2014. We want to hear your thoughts and ideas about how it could be improved.

To suggest changes, you can click 'Discuss' above and add your thoughts to the discussion page, or click 'Submit Comment' at the bottom of the page to send us a comment, or email us at [email protected]

For more information about this standard, see: Proposal for a standard method for the preparation of construction industry knowledge.

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 the need for reprocessing.
  • 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 to 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.
  • Use UK English.
  • Summarise 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. 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.

[edit] Design

Document design should be very simple so that it 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 change page orientation to accommodate images or tables.
  • 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.

[edit] Images

  • All appropriate rights and permissions must have been acquired for images and other material.
  • 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.

[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 information about the source of the content and any licensing restrictions where these are different to the rest of the document.
  • Captions should include a plain language title describing the content.

[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.
  • Licence (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 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.


Do not say image below, above, left etc. Refer to an actual figure number.


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 future tense is limiting.


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?


Text should not refer to images / tables etc that are above, left, right or below, as this restricts formatting. They should refer to a number or title.


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?


Web addresses need to include the http:// bit


Give images (and other files) a plain language name that is east to remember and index but does not include symbols (such as apostrophes or dashes) that might confuse some image handlers.


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


Use standard fonts.


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.