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.

pattern

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Structure

Advantages

Disadvantages

Related Practices

Resources

About

Keep up-to-date!

Powered by