Some rules for effective workplace wiki publishing

This document was first published at Shiro Learning. (Please note: I can’t explain why but when I first set up this Medium account, it copied across automatically from that site to this one. Go figure.)

Introduction

We live in era in which social workplace technologies are already playing an increasingly important role in driving deliberate organisational learning.

This means that to generate reliably “clean” material fit to drive shared learning, you will be best served if you follow content-management processes akin to those established over decades in the world of professional publishing.

In this, if wikis are to be your tools of choice, effective workplace wiki publishing can only result by imposing some of those disciplines, as this really is a zone in which “garbage in, garbage out” applies.

This is not least because too often without strategies for its prevention, garbage in is only compounded by yet more garbage in.

As the example cited here, the failure to observe any such processes by the development team of a Big Four Australian bank meant that its best intentions in documenting its most important web-technology development project will almost certainly never be realised.

So, this is a cautionary guide to lessons learned, and what can go wrong if effective wiki publishing is your team’s goal.

What follows beneath:

• The challenges of putting a new publishing medium in non-publishers’ hands
• You know your documentation regime is failing when…
• Good tools can’t make up for a lack of publishing process
• Your publishing mechanisms need an overarching plan
• You need a process for commissioning new material
• To ensure it meets need and expectation, every word that is written must be reviewed
• You cannot assume that someone will produce something you haven’t asked for
• You need an effective process for retiring aged content
• Too many authors, too little discipline
• What makes managing social content different

The background

Everyone you or I will ever come across is likely to be able to read and write, but clearly when called upon to perform in writing in the workplace, not everyone is well suited to becoming a reporter, an editor or a creator of high-quality documentation.

Those without a love for curating content are especially unlikely to give much forethought to it before they start.

This suggests that in a social technology-enabled workplace there is a new discipline to be built around the organisation of social content if that material’s purpose is to drive learning effectively.

This was one key insight I gained when, after having put in almost 20 years of work as a sub-editor on newspapers and magazines, I spent the second half of 2013 working on a brief to organise technical documentation for a major web-technology project at a “Big Four” Australian bank.

As its communication vehicle, the bank’s development team uses the Atlassian wiki, Confluence, a first-class tool deservedly beloved of technical teams around the world.

I was keen to take on this job for this reason, as I’ve been especially interested for many years in how the content generated by such social workplace technologies can be used to liberate knowledge and drive new insight and workplace learning.

My experience gave me the ability to reflect on what makes for effective social information capture in a well-designed workplace-learning experience.

And, as it is much easier to learn from failure than success, I am extremely grateful to the bank for giving me a more valuable education than I could ever have anticipated at the outset.

In this, I in no way blame the smarts of the bank’s employees, just their lack of experience and inability to give time in a punishing project schedule to understanding the need to impose proper publishing process.

The challenges of putting a new publishing medium in non-publishers’ hands

From the editorial perspective, one of the particular new challenges of using social content as a tool for delivering a reliable learning experience is that it creates new rules for success, precisely because its content creators are not publishing professionals.

This makes the quality of curation key.

Success ultimately will result from the quality of the rules applied at the beginning.

If some of the key rules of publishing are absent, the likelihood grows of the quality of documentation suffering, and it then being misunderstood, left unread or worse, over time, completely ignored.

Yet, with adherence to effective process, all documentation initiatives can improve over time if a small number of simple processes are built into any learning system’s design.

You know your documentation regime is failing when…

• You can’t find a document you are sure you had read before.
• You can’t understand what you are reading because it is either poorly constructed or badly written, with little attention paid to the needs of the reader.
• What you are reading lacks context and you don’t know what its background is, or even if what you are consuming is the most recent version.
• Detail is included without any introduction that guides readers as to what follows, and absent of any summary or explanation as to its appropriateness for purpose.
• You can’t validate what you are reading because the author has omitted key references as to the sources of its content.
• No one has declared it complete, a draft or an initial scoping of a work in progress.

Good tools can’t make up for a lack of publishing process

At the outset at the bank, I was told the purpose of my role was to assist in developing high-quality documentation that could subsequently help future developers learn about the technologies that were its subject.

There was an ambition on the part of the project’s architects that this documentation should be of sufficient quality to be opened up to third-party developers, and that what was often highly technical material should be made more readable for a wider audience.

From a publishing point of view, it became apparent quickly that while it had a goal, the bank’s documentation process was flawed in its design and execution at every level.

None of the processes in place could support or make realistic the team’s goal.

Probably the number one message all future knowledge-system builders must learn is that if you don’t know or don’t express what you want, you can’t expect great documentation as a result.

Moreover, when you don’t specify what you want, you can’t expect someone else to guess how to turn what gets produced into what you want.

Your publishing mechanisms need an overarching plan

Anything designed to be stable needs a plan and solid foundations, and this rule is no less relevant when you build a system for project documentation.

If you can’t do this for yourself, you need to find a professional to help you.

Like anything else, effective publishing follows rules, and one of, if not the first, is to answer what is the goal of the documentation?

If you can define the rules determining the priorities of content creation, you can offer guidance to writers and set expectations for quality and consistency which can feed back into improved system design.

No such system existed at the bank because nobody had given the time to think about it, nor, mid-project, at the time I joined could anyone spare the time to attend to the problem.

You need a process for commissioning new material

Good publishing process typically consists of someone conceiving an idea, deciding what is important to the reader and planning the ways in which that idea might best be explained.

In any medium, this process usually involves an “editor” (a decision maker) in commissioning a story.

Specifying what needs to be included in any document then prioritises what gets written, how this relates to other documentation and how and when the work is to be completed, and by whom.

The story brief might also specify who at subsequent production stages will verify its accuracy and completeness, especially when the material is highly technical.

A system of labelling might also indicate a document’s degree of completeness (draft, complete, on hold, and so on), and another might suggest future dates at which content might be reviewed again for its accuracy and currency if it is to remain on the system.

The consequence is that if you want order, you need someone to play the role of commissioning editor to determine what is to be produced, and what is to be culled.

At the bank, the process fell over at the first step because at the earliest stages of the project no shape had been put around the final documentation expected.

Failing to design a system before construction and then also to assign appropriate commissioning-editor responsibility or oversight at the project-architect level ensured that success at the later stages could never be realised against the declared ambition.

To ensure it meets need and expectation, every word that is written must be reviewed

If you aim to create quality documentation, the process of review by appropriate experts is every bit as important as that of commissioning and creation.

Not least, it is the check that everything that should have been included has been, to the levels of quality expected.

If the knowledge a document contains is highly specialised, this process of review might almost certainly include oversight by an appropriately qualified technical expert to validate the work and its accuracy.

Then, the review for editorial quality should ensure that aims for readability, accuracy and user comprehensibility aren’t corrupted by poor spelling and grammar, or presentational sloppiness.

In the bank, however, because these checks hadn’t been designed in, neither end of this process was present, which meant that through the absence of prescription, a wholly uncertain proportion of its documentation could ever be assumed to jump safely the necessary quality hurdles.

You cannot assume that someone will produce something you haven’t asked for

If you are a specialist in a professional discipline, even if it seems blindingly obvious that a specific document needs to be created, you can never assume that others see things the same way.

It is also unsafe to assume anyone will magically document what you can see as obvious without you first making a request and finding the experts to make it happen.

At the bank, certain of its architects assumed that the documentation they expected had been created where in fact it hadn’t because their needs had never been communicated through any formal process.

Only vague, indeterminate, often apparently contradictory instructions existed, mostly completely lacking in substance or rationale.

You need an effective process for retiring aged content

One the key lessons I found in creating a body of useful content is that before you create more documents, order should be given to content that already exists, or decisions made about what must be retired before adding to its sprawl.

The longer this job is left undone, the harder it becomes.

The more quickly you can impose order on existing documentation, the more quickly will emerge its proper production processes, taxonomies, indexation, relationship to all other previous and future documentation and usefulness to consumers.

Thus, as the rules for creating better documentation become clearer, the simpler becomes the process for commissioning new content, and the more effective becomes the review of everything produced against its specification.

It is easy to overlook how documentation ages in a living system, but at the bank, these problems were compounded by the sheer number of new content producers coming onstream.

Too many authors, too little discipline

By the time I joined the bank’s project, it was already more than six months old.

Technologically, it was a major and radical departure from anything that had existed or been attempted before.

Its complexity embraced a whole new philosophy around which the bank’s architectures were to deliver future services to customers, and another concerning their future development.

Apps of different varieties were to be developed for all mobile platforms (the switch to mobile access of the bank’s web services being one of the project’s initial triggers), along with an underlying platform that would support the delivery of data to those apps and manage progressive evolutionary change between software versions.

From its inception, the system’s several architects had created many documents trying to give shape and a common understanding to the project, many of whose usefulness had degraded over time as one idea had given way to another.

The documents, however, remained incomplete but on the system, undeleted.

Despite the development of high-quality documentation now being a declared project goal, attention to the detail of delivering it was the last thing on the architects’ minds as they continued to give shape to their baby.

Then, at the time I joined, the growth in the system’s sprawling mass of content began to accelerate as a new intake of engineers joined its team.

Common among these technicians’ complaints was that the platform materials they needed to understand what they were doing was missing, because it had never been commissioned or committed to documentation by the architects responsible.

In turn, in articulating their own understanding, they were about to begin adding to its store with their own new documentation, with individual authors creating pages on a whim, the majority of which were never completed.

Some people’s work was also changing too quickly under their feet to merit documentation (one described it as “documenting water”), meaning no one knew where there were holes in the information available.

Compounded by all the usual variegations in the ability to write or to communicate ideas clearly, many being by non-native English speakers, no one could identify which documents had outlived their usefulness.

Making sense of and being able to sort into an index the documentation which contained information that was valid became increasingly difficult as the repository grew.

Because the fundamental rules of creating professional documentation had been ignored, on a project of huge scale, the problems of putting it right in the time scale permitted became pretty much impossible to fix.

What makes managing social content different

When we describe these technologies as “social”, we imply that the creation of their content can be near-instantaneous and fluid, more like conversation, and conversation is notoriously hard to capture well.

The upside is that new contributions, often shared between those who might not work together or know each other, can make quickly for great leaps in new understanding and insight.

When material is created purely for social purposes, imposing order on it might be unimportant.

This, however, presents clear and obvious challenges when referencing or adding context to fluid and dynamic content intended to function as a source of learning.

Unless the right information is available and can be found consistently by applying a similar set of rules that benefit every search, learning will be inconsistent and undependable.

We can also predict that without proper guidance, or checking, not all contributors will be as diligent about the consistency with which they tag, reference and index their own contributions.

Yet, effective indexing and search are really important to the learning experience by providing for continuity of thought, attention and understanding.

Knowledge that isn’t organised with a plan from the outset is very much harder to learn from later.

An index that clearly sets out the order and rationale for what is being documented establishes a starting point, against which context can be understood and purpose can be inferred.

Where doubt remains, it can be checked.

The necessary consequence is that organisations intending to get the benefit of faster learning from publishing through social workplace platforms need also to establish guides for content creation that lay out process priorities for what gets contributed to the body of knowledge.

The alternative is to own the tyranny of an index and store of poor quality content that grows of its own volition, yet which, without proper intervention, yields only a fraction of the value intended.

As those at the bank with any form of dependency on its own body of social knowledge will now attest, as a consequence of the absence of any effective publishing process, this is the only sort of documented technical content this major project now owns.

By any account, this is an expensive lost opportunity.

…

I am a director of Shiro Architects and am leading its workplace research for a book themed, “beyond activity based working”. I started the LinkedIn discussion page, The Learning Economy, and have also just “open sourced” my creation of Investigative Learning, a methodology for improving the ways in which by using wikis to publish organisations can learn by putting to work the knowledge they didn’t know they had.