Saturday 30 January 2016

Tech Writing and Git

The ever-excellent Sarah Maddox has posted her notes from a "Git-based Technical Communication Workflows" workshop she recently attended at a Tech Comms gathering.

For those of you who don't know much about it, Git is a source control repository, although that barely does justice to it's functionality.  Suffice to say it's popular, powerful, free and very well-supported. It's most commonly used for code, but as demonstrated by a couple of demonstrators from GitHub (a very well-known Git repository hosting service) it can also be used for documentation.

I won't spoil the surprise by giving you any previews, but if you've ever considered using version control for your documentation then Sarah's article is a must.

Oh, and how much do I want one of the GitHub Technical Writer Octocat stickers??  Got to get me to a conference soon.....

 

Friday 29 January 2016

Decisions, Decisions......

What is it that separates a manager from a non-manager?  Is it skills? Experience? Age? Brown nosing?  No, it's none of those things.  Or at least, it shouldn't be any of those things.

What separates a manager from those who aren't managers is the willingness to make a decision, and to be comfortable with that decision.

Yeah, that doesn't sound like much of a difference, does it?  But oddly the important part is not even the willingness to make a decision. Lots of people are willing to make a decision, or so they claim.  Many, many people talk the talk, but when it comes to walking the walk, especially for a decision that could have business ramifications or requires other people to do things, they suddenly develop cold feet and come up with a reason why they shouldn't make that decision.

Some of the people you know who are managers, according to their title, will be like this.  They'll have to make the decisions because that comes with the job, but they'll put the more difficult ones off until they absolutely can't avoid it, and when they do make them they'll be defensive about it and irritable about the outcome until they're certain things haven't gone wrong.  They may even delegate the decision-making responsibility to a member of their team, and then use that person as a human shield if things go wrong. "Well Joe made the decision, and he IS the technical expert."  Or the horrible, insidious "I trusted Joe and he let me down.  It's my fault, I shouldn't have given him the responsibility.", thus throwing poor Joe under the bus whilst simultaneously playing the victim.  Urgh.  (If you've ever worked for that kind of manager, this will be familiar.  If you still work for that kind of manager, get the hell out before your career at that company is tainted by their sly putdowns and gradual breaking of your self-esteem.)

This is why being comfortable with dealing with the consequences of a decision is the most important factor.  When you're not scared of the ramifications, when you believe in your judgement, decision making is easy.  That doesn't mean it's always quick, and it doesn't mean the decision itself is always an easy one.  It might take quite a long time to come up with a decision, especially for a contentious one where there are 2 (or more) opposing schools of thought on a subject.  But the act of making the decision will be easy, and the feeling afterwards will not be one of terror or dread. The manager who doesn't trust themselves, or doesn't have the technical knowledge to understand the import of the decisions they're making, will be the ones who throw their staff under the bus.  A manager who trusts their own judgement and has a decent handle on the important parts of their area of responsibility is much less likely to do this (Although, some people are just terrible human beings.  But we're not talking about that here).

It's ok to be worried about what will happen when you make a big call.  That's human nature. But it's a rare management decision that should keep you up at night. Decisions have to be made. Sometimes very important decisions.  Being able to make them and then explain them to others afterwards is a key part of management.  As you go up the chain of command and do less managing and more leading, decision making becomes even more important.

Of course, you can be good at making decisions without actually making good decisions. Your decisions might be crap, and that's not a good thing.  Likewise there are many other important qualities that a manager needs to be good at their job, such as putting their team first, finding the right balance between detail and big picture, not trying to build empires, and so on.  But you can be all of those things in non-management positions without being able to be a manager.  It's decision making, and being comfortable with your decisions, that really separates the managers from the non-managers, regardless of job title.

The good news is that you can learn this, and I really hope you do if it's not already in your tool kit.  Manager or staff, leader or follower, you can learn to make a decision and not second-guess yourself constantly afterwards.  And once you do, there's no turning back.  It's like a ladder that you kick away, and once it's kicked you can't climb back down to be a person who's afraid to make decisions. 

Tales of decision-making woe are encouraged in the comments :-)


Saturday 23 January 2016

Is Knowledge Management the Same as Documentation?

This is an interesting question.  Traditionally, technical writing covers the production of documentation that explains the functionality of what we can call, in the absence of a better catchall term, technical things that are produced by engineers.  These technical things could be anything from mechanical to electrical to electronic to programmatic.  Technical writers produce documentation that covers the installation, configuration, integration, support, maintenance and usage of these technical things.  This isn't a new phenomenon either; writers have been producing what could be called technical documentation since well before the industrial revolution (a particular favourite being Kitab Aniq fi al-Manajaniq (كتاب أنيق في المنجنيق, or An Elegant Book on Trebuchets) which was written in 1462 by Yusuf ibn Urunbugha al-Zaradkash).

Knowledge Management (KM) is a much newer profession: it became a discrete discipline in 1991 with the publication of The knowledge creating company by Ikujiro Nonaka in the Harvard Business Review (which you can read online at HBR here).
  Although philosophers have studied knowledge for millennia (Plato was writing about it in Ancient Greece nearly 2500 years ago, and he was almost certainly not the first person to do so), they weren't studying it with a view to making sure people captured and shared their knowledge, which is the main goal of a KM professional.  Philosophers were, and still are, more concerned with what knowledge is and the difference between certainly, belief, knowledge, etc, and although that's very interesting from an intellectual point of view, it's not overly helpful in practical terms.  KM doesn't have the history of technical writing, nor does it come from the intellectual highlands like the study of syntax and semantics do (both of which are key to effective technical communication).

And yet because documentation now comes under the auspices of KM in many places, so must technical writing and therefore technical writers.  This makes sense, because if the goal of a knowledge management system is to make sure that the knowledge in people's heads is captured and shared, then you will need technical writing skills to document what is captured.  And in those places where technical writing is not explicitly line-controlled by KM, perhaps because there is no explicit KM function or because KM and technical writing come under different reporting lines (e.g. product management and development), it's still hard to see how you could implement a robust KM programme without your writers being involved in some way.

This though begs the question, does it not? of whether KM is actually just a fancy phrase for technical communication. The goal of technical writing - to explain, elucidate, inform and teach through the medium of written documentation - is one of knowledge transfer through capturing and sharing knowledge.  A Documentation Manager will be responsible for, amongst many other things, laying down standards for information capture, such as information from developers about issues they've fixed; it is a short hop to say that these standards should be slightly expanded to include the capture of other information that needs to be written down somewhere, even if it won't go into explicit documentation sets targeted at specific users.



Of course, KM has its own language: You encourage knowledge sharing, with the aim of building a knowledge ecosystem, a place where the codification of knowledge is performed collaboratively by expert practitioners who can explain and illuminate both their explicit and implicit knowledge, with the ultimate target of having a complete record of the output and metadata of your human capital. KM experts will make references to culture, process and technology forming a tripartite foundation on which a company's knowledge management programme will stand strong for decades, or crumble into the dust. 

But such language is often just a label for a more complicated concept, a short cut for adepts to use in cultured conversation.  The technical writer, when talking about the use of DITA in a single-sourcing environment as part of a content management strategy, is doing no different.  These languages should not be mistaken for the practises themselves; the language may be a point of difference, but that doesn't mean that the practises of a KM professional and a documentation professional are therefore automatically different. A "punt" in American Football is no different to a up-and-under in Rugby Union (the synonym "huge Garryowen" - thanks to the late, great Bill Mclaren - is also identical in practise).

The practises of technical communication and the practises of KM, especially when viewed through the different lenses of their languages, may seem divergent, particularly for the practitioners of each, but the goals and intentions of technical writing and KM are almost identical.  The practises too, cover a lot of the same ground: information gathering, analysis, writing and sharing the result of that writing. However, there are differences between KM and documentation, and the two primary ones are:
  • Scope
  • Responsibility 
A KM professional normally has a greater scope of work than a technical writer.  Where a technical writer needs to write documentation (which includes information gathering, content creation, editing, and so on), a KM professional needs to be charge of the documentation, delivery method and gap analysis, as well as driving a culture of collaboration, knowledge sharing and training.  Correspondingly, the technical writer will have a deeper knowledge of one aspect of KM - documentation, and all of the attendant skills that are required to produce it - and the KM will have a broader knowledge that encompasses documentation as one (critical) part.

Related to this is the level of responsibility.  A technical writer normally has responsibility for creating content themselves, whereas a KM professional has responsibility for getting others to create content.  Both cases are value multipliers, because the technical writer makes public that which was previously private and the KM professional does likewise, but the KM professional does it by making as many people as possible into value multipliers by getting them to create content and share it.   

Whilst it might seem that the KM professional is therefore more valuable, it is also the case that with this increased reward comes an increased risk.  Content that is created by people who are not trained documenters can be confusing, inconsistent and incorrect; it rarely follows standards for terminology and structure, and tends towards the scattershot approach of "write everything", which means that users have to work hard to sort the wheat from the chaff.  Whilst these problems can be ameliorated to an extent by documentation tools that force users to do certain things (such as templates, mandatory metadata entry, obligatory skins and formats, and so on), there is only so much that automation can achieve.  The return on investment of hiring a professional writer to produce documentation, or at least the most critical documentation, cannot be underestimated.

Another interesting, although perhaps localised, difference is that KM is often seen as a more dynamic role than that of a technical writer.  KM is a collaborative exercise with collective benefits, as opposed to being a job for a specific team, like technical writers, which the collective doesn't always recognise as worthwhile.  This shines a light on part of our psychology: Everyone wants documentation when they don't know something, but few are willing to create documentation that explains what they already know.  In a good KM programme, there is an acknowledgement by the majority that if each individual documents their knowledge then everyone will benefit.  Therefore it is in the interests of the individual to contribute, especially if there is any sort of public register of those that have and haven't contributed. On top of this, the idea of a gift economy comes into play, and people who have the knowledge often like to give it away as an act of largesse to show how much they know. (You may call this ego if you wish, but for me that's too pejorative.)

Where there is a specific documentation team, there is generally no sense of people using a gift economy.  It can become a chore for people outside of the documentation team to have to write things down, because they only see the benefits to others, not to the collective or to themselves, even though the outcome is largely the same.  It's as if they feel they are doing the job of the technical writers for them.  For this reason the KM programme's emphasis on collective responsibility can be more effective.  I won't say much on this here, but I leave it as a point of interest for those who think about such things.


In conclusion, KM and documentation are not the same thing.  Where both are present, documentation is one part - albeit the most critical part - of the KM process.  KM can be seen as a framework in which documentation sits.  Of course, this isn't the only framework and a KM programme is not required in any way to give value to documentation.  But where KM and technical writers work together, KM should provide the direction and culture, and technical writers should provide some of the content and make sure all of the content forms a coherent whole.

As always, your thoughts are welcome in the comments section.