Building Information Modelling (BIM) for content

Building Information Modelling (BIM) is an increasingly popular technique used in the construction industry. It involves creating XML digital models of buildings and tunnels during each stage of a project. However, these are more than just 3D animated models, as they also embed information about physical objects in the building. According to Wikipedia:

“A building owner may find evidence of a leak in his building. Rather than exploring the physical building, he may turn to the model and see that water valve is located in the suspect location. He could also have in the model the specific valve size, manufacturer, part number, and any other information ever researched in the past, pending adequate computing power. “

It means architects and engineers can “see” behind walls and discover if there are any pipes or cables that might be affected by any planned works.

This concept of an intelligent model that can be shared between stakeholders throughout the whole lifecycle is also the future for content. Organisations want the ability to know how different items of content are related, what is the structural and metadata information behind the presentation layer and how content has developed chronologically. They want the ability to use a model to plan and modify before they start the more costly work of implementation.

BIM could perhaps provide a useful analogy for Technical Authors, procedures writers, and others developing text-based content, when they are explaining the purpose and value of structured content, single sourcing and Component Content Management Systems.

SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

Continue reading

Assessing the potential savings from single sourcing

One of the main benefits from single sourcing is the ability to reuse existing content. Different departments can avoid duplicating work, which means they can save time and money.

Unfortunately, it can be difficult to quantify these savings before you move to an authoring or content management system that enables you to single source. Analysing all the existing documents in a business can be overwhelming, which means often organisations only quantify the savings after the single sourcing content management system has been implemented.

There are a few software applications that can help you analyse your existing content and determine how much duplication exists. You get a sense of how much time and effort was wasted in the past, which is a pretty good indication of how much waste you’d avoid in the future.

Continue reading

Planning and running a documentation sprint

Atlassian’s Sarah Maddox has posted her slides from her STC Summit 13 presentation “Doc sprints: The ultimate in collaborative document development”. It’s a useful description of a documentation sprint and its benefits:


Contact Cherryleaf if you’d like help and assistance in managing a documentation sprint.

New University of Oxford research shows surprisingly high numbers of out-of-control technology projects

What the customer wanted cartoonResearch conducted by two Oxford academics (Why Your IT Project May Be RiskierThan You Think) has suggested that the private sector has almost as much difficulty managing big software projects as the public sector. It also indicated that some types of projects have put companies’ survival at risk.

Whereas government departments can experience almost permanent revolution, private sector processes, in general, remain fairly stable. So it’s depressing to learn one in six of the projects they studied was a “black swan” – with a cost overruns of 200%.

The causes include: technology that doesn’t work, the difficulty in accommodating the exception cases, managing large teams, changes to the scope of the project, dealing with legacy systems, changes in legislation, and failing to build a system that meets the users’ requirements.

The researchers recommend breaking projects into smaller, more manageable units and using the best possible forecasting techniques.

There’s an additional problem: systems that work technically can still fail. If the user does not understand how to use the system, or if they don’t understand the benefits of using it, your “successful” system can end up under-used. User Assistance (online Help, Getting Started guides, screencasts and so on) mustn’t be forgotten. It’s one of those final steps in a truly successful project.

How can a Technical Author find more time to write user documentation in an Agile environment?

Agile planning board Flickr Creative Commons image: VFS Digital DesignWe’ve been working on a white paper that looks at how User Assistance can be more effective and developed more effectively when you’re working in an Agile environment. The white paper should be published in the next few weeks, but here’s a sneak peek at one of the issues we discuss: the lack of time available for creating User Assistance.

Agile’s iterative release of products, and sometimes frequent changes to the functionality and the User Interface, can make it difficult to create the user documentation. The Technical Author can end up having to rework content they’ve written, delete sections on functionality that’s no longer part of the product, and add information on features that have been introduced towards the end of the project. If the Technical Author waits until the product has been completed, they can find they have very little time available for writing the user documentation.

So what can you do about this?
Continue reading

Is “document late” a good idea?

One of the strategies in the Agile methodology is to create documentation as late as possible. Is this actually a good idea?

According to Scott Ambler:

A common agile practice is to defer the creation of all deliverable documentation as late as possible, creating them just before you need to actually deliver them…Fundamentally, this strategy is to wait until the information has stabilized before you capture it in documentation.

The reason for this harks back to one of the “three wastes” of the Toyota Production System – the waste of muda. The goal is to eliminate the time spent on activities the customer will never receive or would be willing to pay for.

However, there may be situations where documenting late results in one or both of the two other forms of waste – muri and mura. Muri means overburden – overloading or making things too difficult for certain teams within the production process (and/or for the customer). Mura means unevenness – which can lead to unnecessary waiting time for certain teams within the production process (and/or, again, for the customer).

If the cost of these wastes is greater than the waste of documenting sections that are abandoned at a later stage, then it may make sense to abandon the idea of “document late”. In order to be able to make this judgement, it is essential Technical Authors measure both the value of the documentation (e.g. the productivity of the user, the number of support calls, the number of times it is used) and the cost of producing it. With this data, Technical Authors can then make a stronger case for modifying this practice within Agile projects.

Towards Agile authoring

Agile programming has grown in popularity, and it has lead to new challenges for those involved in providing User Assistance for those applications.

So is it time for Technical Authors to develop an equivalent method for developing content for these projects? Is it time to develop an “Agile authoring” methodology?

Such a method needs to complement Agile programming, but it may be a mistake to take Agile programming as the starting point for developing it. The developers of Agile drew upon the principles of Lean manufacturing, and perhaps Technical Authors should do the same.

What would we be likely to see in such a method? Here are some suggestions:

  • One piece flow. Information is moved through the process in the smallest batches possible. For example, translators and reviewers receive content topic by topic (or chapter by chapter).
  • Minimalist manuals. Only the information that adds value to the user, or increases their productivity, is included.
  • Incremental publishing of content (and frequent builds of drafts).
  • Documentation sprints through collaborative authoring.
  • Rigorous testing and measurement of the value of the documentation.
  • “Stop the line”. Authors have the right to stop the development of software if they spot a critical mistake or if they are overburdened with work.
  • Separation of “look and feel” from content, to enable adaptation to change.
  • Iterative updates to the content.
  • Close daily cooperation and communication with the development team.
  • Removal of “waste”, such as waiting for new information or overload of work.
  • Buy-in and commitment from all the stakeholders of the value and need for the User Assistance.

What would you envisage an Agile authoring methodology to contain?

Addendum: A further point for the list:

  • Creating information that reduces “waste” at the user’s end. In Japanese, there are the concepts of go no sen (reacting), sen no sen (a simultaneous response) and sensen no sen (preempting).  Writers could aim for sen no sen or ultimately sensen no sen –providing information that preempts problems.