Agile Documentation

Space shortcuts

Page tree

 

 

Physical Location

Store information physically only by properties that are invariant.

Domain
Documentation
Type
Knowledge Organization, Coherence
Principles
Stable Dependencies Principle, Separation of Concerns

Each time a new document is to be created, a location to store it is required. Finding the right location may be cumbersome for the author. Finding the document by browsing may be difficult for the reader who demands the information.

How should documents be organized physically?

Structure

If you store a document by properties that may change in the future then not only the document has to be changed, but also the location the document is stored. This should never be the case since changing the location may call for a large amount of work.

Ideally the users of a document are not concerned with the physical location of a document. The may drop the information in any location knowing that there are a lot of views that support readers to find the content by its categories.

Advantages

  • If the physical location is determined by invariant information of the document, the document will never needed to be relocated.
  • If the physical location is something an author does not need to bother about, resources are free to invest in delivering information.

Disadvantages

  • Additional views are required to organize the content for different audiences. But a physical location will nevertheless only support one view for one audience.
  • An invariant information may be hard to determine. The type of the document is typically something that will rarely change.

Related Practices

The following practices are related to this practice.

Favor flat Hierarchies
Organize information physically in flat hierarchies. Add views to put these documents in different contexts.
Focus on Content
Make it easy for knowledge workers to focus on content and remove the need to define the document structure and formatting on a ad-hoc basis.
Welded Lifespan
If documents are added as children to a document, these documents share the lifespan of the parent. If the parent is removed, so are the children.

Resources

For more information regarding this practice please refer to:

Document Type
A document type (doctype) defines the properties and section for document instances. It also provides home and index pages. In Confluence these doctypes are implemented as page blueprints, usually with one template. This template is used to create new pages in Confluence.
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.
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.
Document Type Homepage
The default homepage for documents of a given type.

About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH