Some rules for effective workplace wiki publishing as a vehicle for organisational learning development and growth

In a knowledge-driven age, having a plan for the well-managed collaborative capture, development and retention of what is known and that which must be acquired can deliberately accelerate the speed at which organisations learn.

This practice can effectively overcome artificial barriers, allowing workers to communicate differently within their teams and across levels, roles, and an entire organisation.

Setting up a system for its safe indexing and ready referral also provides for business continuity, as well as important insurance against key individuals or even whole teams disappearing with the critical knowledge on which the business is built.


I first published a variation on this piece on LinkedIn and later made modifications in the wake of a subsequent publication of another related item by global management consultancy McKinsey addressing the uptake of social technologies in the workplace.

McKinsey wrote that according to its own survey work, workplace social tools were at last transforming the ways in which people communicated and worked with each other. Now, it said, employees relied more often on social methods of communication in their work than on traditional methods.

It suggested that the use of advanced tools had implications for broader process-level and organisational changes, with its respondents saying the use of social tools had enabled employees to communicate more often and to self-organise with team members.

Some said these technologies had changed the very nature of their work to become more project based, rather than team or function oriented.

McKinsey reported that respondents said they now communicated differently within their teams – and across levels, roles, and their entire organisations.

It also concluded that on the march to transforming their businesses with digitisation in mind, any improvement via social tools must begin with people changing the way they work first, then using the tool that fits best.

Too many, it says, made the mistake of working the other way round, of choosing the tool first and then expecting change to follow.

If reliable business learning and knowledge-creation are the intended result, I believe that because it leads new ways in which a business can learn to think new thoughts, McKinsey’s assertions also support the case for taking greater control of the quality of socially published material in circulation.

This, not least, will help to identify and reward the real knowledge creators and drivers of learning within an organisation, such that their model can provide the template for future organisational advance and learning-driven recruitment strategies.

Get to grips with the new tools of learning

Amid increasingly pervasive social internet literacy, social workplace technologies aren’t going away.

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

Because these principles have been proven to work effectively, they are essentially the same, wherever they are exercised, and regardless of medium.

If wikis are to be your tools of choice in promoting business learning for transformation, 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, my personal experience of the failure to observe any such processes by the software 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, but its realities aren’t managed.

What follows beneath

  • The background
  • What is a wiki?
  • 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
  • What is the most important standard in publishing?
  • 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, with too little discipline, will result in a mess
  • 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. However, 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 effective sharing-based learning.

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 had been especially interested for many years in how the content generated by such social workplace technologies could be used to liberate knowledge and drive new insight and workplace learning.

My experience at the bank 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 more powerful to learn from experiences that don’t go quite as planned than from outright 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 any one of the bank’s employees engaged in the project. Shortcomings just lay in their lack of experience and inability to give time in a punishing project schedule to understanding the need to impose proper publishing process.

What is a wiki?

Represented as a web site, a wiki is essentially a database for creating, browsing, and searching through information.

It is developed collaboratively by a community of users, and a defining characteristic of wiki technology is the ease with which pages can be created and updated. Any user may add and edit content by using any standard web browser.

Generally, there is no review by a moderator or gatekeeper before modifications are accepted and therefore lead to changes on the wiki site.

For all of these reasons, whatever other tools may be engaged, a wiki is an ideal tool to create and update a body of organisational knowledge dedicated to driving its team’s creativity and learning.

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, as success ultimately will result from the quality of the rules applied at the beginning.

If some of the key publishing disciplines 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…

  • There is no system of indexation or ready retrieval.
  • 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 that goal realistic.

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 to be written, 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 you want into what actually gets produced.

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. Simply because creating quality professional documentation wasn’t everyday core business, nobody had given the time to think about it, nor, mid-project, at the time I joined, could anyone sufficiently senior spare the time to attend to the problem.

What is the most important standard in publishing?

Most industries have standards, such as the ways in which in Australia all plugs for electrical devices fit standard mains points to draw on the energy they supply, at a common voltage.

A USB plug on a computing device will work on any product with a USB port; the World Wide Web uses internet protocols to deliver web pages reliably via any compliant browser; a telephone handset can receive a call from any other; and so on.

Publishing itself is driven by precedents of process and error checking rather than standards per se, but for one.

If you look at any print publication, for example, it has an index, which tells you what information can be found and on what page, and how it relates to other information in that section.

If you want to be successful in publishing pretty much anything, and you want users to be able to use your content, begin with an index.

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, or “commissioning” editor) in commissioning a story.

Specifying what needs to be included in any document then prioritises what gets written, how this relates to other documentation, via the index, 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.

When that date is reached, decisions can be made about how to retire it, update it or create a new document.

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 index existed and 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 exist or 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 key lesson 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, because the process of review is infinitely more challenging than that of creation, and especially when context is missing.

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 those who need to use it.

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, with too little discipline, will result in a mess

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 those underlying architectures’ own 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 this, an underlying platform was to be implemented 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”). This meant 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 available permitted became pretty much impossible to fix.

What makes managing social content different

When we describe these workplace 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 ease of consumption, continuity of thought, attention and understanding.

Poor quality documentation will deter readers, and 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.

Documents can always be downgraded, removed from view or deleted later.

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, and only a cost, not an asset, to the bank’s continued learning and communication.

The optimistic upshot

As a consequence of my personal experience, I have evolved “narrative learning” as a means of creating documentation equal to the task of driving learning by engaging the common social internet literacy that now exists in any organisation.

Done well, it can effectively put to work the knowledge many businesses simply don’t yet know they possess.