A reflection: Some rules for effective learning from workplace wiki publishing

Introduction

Because they can capture many diverse perspectives across an organisation, social workplace technologies present great opportunities for stimulating collaborative learning.

This offers a lot of scope for using an organisation’s knowledge to design its future.

But, like any project, doing this well requires a sensible process and definition of scope.

My purposes here are to lay out some fundamental principles for managing social workplace content to deliver a more reliable collaborative learning process.

Regardless of purpose or medium, for an audience to have the best possible chance of understanding your documentation consistently, you need to follow a disciplined publishing process.

That is, you need a delivery system which declares a targeted end point and how a given publication goal will be achieved, its attainment recognised and its results checked and validated.

The ideal, both from the needs of the reader to those of the producer, should be to create something as familiar and easy to consume as a magazine or book, and as searchable on keywords, terms and authors as the web itself.

There should be a clear table of contents dividing material by subject, project stage, organisational division or simply whatever makes reference by the user easier.

Finally, you need a process by which content is to be added, monitored and/or deleted.

As a case study in how and where such goals might not be realised, I document beneath my own experience in 2013 of working to document a highly technical, large-scale software development project at the Sydney Darling Harbour headquarters of the Commonwealth Bank of Australia (CBA).

My intention here is to describe, for those who may be interested, and from a straightforward publishing perspective, the reasons why its aims would almost certainly never be satisfactorily realised.

The new challenges of social documentation

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 social 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 consistently and effectively.

This was a key insight I gained when, after having put in almost 20 years of work as a sub-editor on newspapers and magazines, I joined the CBA project.

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

As I’d 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 organisational learning, the learning this would give me was fundamental to why I wanted to take on this job.

And as it is much easier to learn from under-achievement 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.

Its architects, developers and their managers simply lacked time to take on the task of thinking about documentation while they were busy inventing and building their new products.

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

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 their purposes.
• 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.

The scale and scope of the bank’s technical project

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

Technologically, its undertaking 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 web 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.

This required the bank to rethink its entire architecture, from its continual development “devops” delivery platforms and processes, from the ground up.

It engaged a team of somewhere between 200 and 400 mainly engineering and technical staff.

And that was the beginning of its publishing challenge.

Omitting the overall organisational and technical goal described in those last few sentences, and the motivations underpinning the task, all of the moving parts were in design and being built at the same time as it was to be documented.

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

Yet, to give attention to the detail of delivering this goal was the last thing on the architects’ minds as they continued to give shape to their baby.

As one of my engineering colleagues described to me early on, because in many respects it was being built as it was still being imagined and designed, “You are trying to document water.”

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

From an editorial perspective, the fact that social content creators are not publishing professionals presents a particular new challenge if content is to be used as a tool for delivering a reliable learning experience.

This makes the quality of curation key.

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

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

This was the risk the bank faced.

Yet, with adherence to effective process, all documentation initiatives can improve over time if certain fundamentals are built into any learning system’s design.

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

It became apparent quickly at the bank that while it had a goal, great technology and clever people, there was probably no level at which the design and execution of its documentation process could not have been considerably improved.

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.

You need a process for commissioning new material

Probably the number one message all future knowledge-system builders must learn is that if you don’t know or cannot express what you want, you will have a difficult task in getting great documentation.

That is, if you can’t specify what you want, you can’t expect someone else to guess how to turn what they produce into what you want.

At the bank, at the time I joined its project, content was being produced, thousands of pages of it, seemingly almost randomly.

Yet, good publishing process is anything but random, and typically consists of conceiving an idea, deciding what is important to the reader and then 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 the piece in question.

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.

A system of labelling might also indicate that degree of completeness (draft, complete, on hold, awaiting review, 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, what is to be kept and what 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.

There was no agenda and no table of contents defined.

Failing to design a system before construction, and then also to assign appropriate commissioning-editor responsibility or oversight at 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 written must be reviewed

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 they 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 discipline, even if it seems blindingly obvious that a specific document should exist or 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 prescription or rationale.

You need an effective process for retiring aged content

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.

In creating a body of useful content, one key rule 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 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.

The longer the job of retiring aged content is left undone, the harder cleaning that body of documentation becomes, undermining the motivation of users to use it.

Too many authors, too little discipline

At the time I joined the project, 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 also completed.

No one knew where the holes were in the information available.

Compounded by all the usual variegations in the ability to write or to communicate ideas clearly, 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.

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 organisation-wide 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.

Conclusion

Organisations intending to get the benefit of faster learning from social workplace technologies need 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, this is probably the only sort of documented technical content this major project now owns.

By any account, this is an expensive lost opportunity.

In short, if they are to prove effective, social workplace publishing mechanisms need an overarching plan

So, if you can’t do this for yourself, you need to find an appropriately qualified professional, one who really cares about this stuff, to help you.

………………………………………………………………………………………

This is a blog of Shiro Architects in Sydney, Australia, which is building a practice based on an understanding of knowledge architecture.