Standard Layout

A standard layout makes it easier for new members of a team to find information. A standard layout is project independent and is typically defined by an organisation.

Domain
Software Design
Type
Knowledge Organization, Collaboration
Principles
DRY Principle, Principle of least Astonishment

An author needs to add a new document to an existing documentation. This document should be stored in a place where other authors are looking for.

How can we support authors to find the place for a document where readers and especially other authors are looking for?

Structure

Adding new documents to an existing documentation is easier if there are some basic rules to follow. These rules define which kinds of documents are stored at which location.

A standard layout for organizing documents is defined by an organisation. This layout is used in many or all projects of an organisation, making it easier for new team members to get started.

The projectdoc Toolbox provides homepages for doctypes which function as standard locations.

Advantages

  • New team members who have worked with other teams have an easier start in a new project. They already know the standard layout and know where to look for which resources.
  • Readers may not be dependent on the standard layout, if they can rely on multiple views.
  • The chance of duplicate documents is reduced if the author finds all related documents in the standard location the new document will be stored at.

Disadvantages

  • A standard layout must be defined and established. This requires resources.
  • A standard layout may be different for different kinds of projects. This would reduce the benefit of the investment of a standard layout.

Related Practices

The following practices are related to this practice.

Physical Location
Store information physically only by properties that are invariant.
Provide multiple Views
Provide views on your topic-based documentation.
Favor flat Hierarchies
Organize information physically in flat hierarchies. Add views to put these documents in different contexts.

Resources

For more information regarding this practice please refer to:

Home and Index Pages
Home and index pages help to organize documents by type. For each doctype there is a homepage and and index page. The homepage shows the central documents that are added to it (immediate children). Index pages list all documents of the space, regardless of their location.
Specify Doctype Homepage
It is easy to define the default homepage for a given doctype in a space.
projectdoc Spaces
projectdoc introduces structure on a Confluence space. It adds the concept of homepages for document types.
Think Repositories
To organize your documentation place documents in a typed repository and add additional views on demand.
Document Types and Templates
Document types (or doctypes for short) define a set of properties and sections. Each doctype matches at least one Confluence Page Blueprint. Confluence Page Blueprints are a collection of templates, but often the collection contains only one element.