Saturday, 29 July 2017

5 Things Writers Need From Developers


Developers don't like writing documentation in the same way that cats don't like having a bath. There might be the odd breed of cat that likes a bath, just like there is the odd developer who likes writing documentation, but generally cats and developers are quite predictable when it comes to baths and documentation.

But people like being able to get necessary-but-onerous jobs done with the minimum of effort, time and thought, and developers are no different.  So here is a list of 5 things writers want from developers. 
 

Clarity 

Don't provide a steam of consciousness brain dump about the work item you're documenting.  List things in some kind of order.

Accuracy

Can't remember why you added a radio button to the UI?  Don't make up an answer.  When you're not sure, tell us you're not sure.  If you know the name of someone who might know, give us that name.  We'll do some legwork for you.  But don't ever make stuff up.  

Timeliness

Not just about when you get the docs to us, but when you write them.  Yeah, the next piece of work you've been looking forward to is much more interesting that documentation, but tough luck.  Your memory is fallible and you will forget details of the work you've done.  So either document as you go, or at least document before you move on to the next piece of work.  It will save you and the writer a lot of pain later on as they have to spend time interrogating you and your terrible memory.

Completeness

Also known as 5WH: What, When, Who, Where, Why and How.  WHAT was done, WHEN was it done, WHO did it, WHERE was it done, WHY was it done, HOW was it done.  If you take nothing else away from here, remember 5WH.  

Consistency 

Provide the same information every time in the same place.  Create a template.  Ask the writer to create a template for you.  Get every developer to use the same template and save it in the same place - a new Confluence page in the Release space for every work item, in the comments of the JIRA item, in a dedicated Slack channel for that release, in a README for every GitHub pull request, wherever works for the team.  Then do the same thing every time.


Some notes on the above:

  • There are pieces of information that it's just common sense to include, like the names of people who worked on something and the numbers of linked work items.  Forgetting to include these makes you look anything from unprofessional to incompetent.
  • There are pieces of information that the non-writer may not think need to be included.  Ask the writer if they want that information included.  This is one of the ways a template really helps.
  • Writers hate it when their work can be called into question, especially if it's because a developer has fed them some made-up information.  Reputation is important to writers, so don't make them look bad at their job. (This is a pretty good rule of thumb for all interactions in your life.)
  • Being part of the "too cool for school" culture that mocks people, especially developers, who write documentation is boring, unprofessional and frankly pathetic.  It's part of the "bro culture" that everyone hates (apart from bros, obviously).  It should be embarrassing to you if you get your kicks from ripping on other professionals in your office.  Stop it.  If you're reading this then hopefully you're not that kind of developer.  Spread the professionalism around your office as required.
  • Developers who write good docs are normally the better developers in the office.  Writing good documentation requires you to be able to step into someone else's shoes, as does writing good software.  The most respected (and best paid) developers I've worked with over my career have significantly overlapped with the developers who write good documentation. 
  • When all's said and done, developers need to communicate what they've done, whether they want to or not.  Learn how, become a better developer, become a better professional.

 

Sunday, 19 March 2017

The Craftsmen and the Chart-Makers


We don't make anything any more.

That lament has followed us through the years as a ghost floats above his killer, never seen with the fullness of the eye but always hovering as a mocking, aggressive reminder of what we've done to ourselves.  We've killed our ability to make things, outsourced it to the non-Western world in return for self-righteousness about the lack of pollutants in our post-industrial lands, while we wring our hands about the plight of the people in those barren places where the machinery has cooled and seized.  Statues of steel and rust in yellow, grey and brown, abandoned as a warning to our children, mnemonics to those of use who saw them in their prime, moving, growling, far too large to ever be killed, or so we thought. 

And who is to blame, cry all? 

The politicians! The corporations! The environmentalists! The unions! The liberals! The elites! 

Each one says, "But, 'tis not us! We only wanted a clean, technologically-advanced land, where people are educated, work is skilled and life is good! Why do you blame us for the best of our intentions?"

And the politicians blame the unions, the corporations blame the environmentalists, the environmentalists blame the market, the unions blame the liberals, the liberals blame the elites, and the elites melt into the ghost that haunts our waking and takes what's best from our sleep.

But many have never seen a post-industrial land, let alone an industrial one.  Their concern for what we make is limited to discussions about tax, custom tariffs, import and export ratios, figures upon figures arranged in industry-approved charts of all kinds, a blanding of the sweat, effort, sacrifices and pain of the makers into black digits in a white cell.  Not for them a life steeped in the stink of manual labour, the ache of muscles from a 12-hour shift, the primal satisfaction of using the power of your body to provide for your family.  These are things that belong to a different age, an age of flat caps worn without irony, holidays to the seaside, outside toilets, knowing your neighbours your whole life, living, dying, generations of people, within the same county border, the same town, the same village, the same factory or mine or mill, the same house. 

A German and his English colleague once talked with horror of man becoming a mere appendage of the machines, workers being no longer the means of production but lowly attendants on those mechanical monsters that have taken over the effort, the sweat, the pride of making things.  A portent of what is to come?  The chart-makers delight in this thought, this hope, for all they see is minimum costs and maximum production, a line on a graph that moves smoothly and predictably in their favour in a mathematically optimal way.  The messy meat variables are being replaced with pristine metal constants.  Is this not utopia?  Is a land built on the cool predictability of the voiceless machines not better than one uncertainly sustained by the chaos and noise of a directionless mass of writhing limbs?  So much chaos.  So much noise.  So much complexity, too much complexity, a rabble of variables that moves the chart further and further away from a prediction and closer and closer to being no more certain than a prophecy.  This is not what the charts should show.

The chart-makers say: These lives are an anachronism!  We don't need them.  We need the figures to balance in our favour, and if they balance in our favour then the anachronisms will have work to do somewhere else.  And eventually the figures always balance in our favour.  Eventually, but always.

All hail the chart-makers, for they shall inherit the earth! 

We don't make anything any more.


But we do.

The chart-makers just can't see it.

......

When steam relegated the horse to a luxury, the wailing sounded a keen note.  Blacksmiths, tanners, farriers, your services are no longer needed! You shall drive trains, mend engines, cast metal, all to feed the new metal equines!  Things will be more efficient, quicker, more productive.  We can do the work of 10 men with 1 man!  Those who tallied ledgers laughed excitedly at all the black ink they would need for their account books; surely red ink would be the preserve only of those unfortunate enough to find themselves on the wrong side of this revolution?  But red ink continued to be produced, and the crafts that had been practised for a thousand years were slowly forgotten.

Then, a century hence, the wailing begun again.  Steam?  A historical irrelevance! Internal combustion and electricity are far more reliable, efficient and predictable. No more water towers to fill and maintain at every station, no more coal stokers, no more steam engineers!  And these crafts also fell into abeyance, replaced with electricians and mechanics who each did the work of 10 men.  And still the red ink was needed by those who tallied ledgers, their initial excitement gradually worn away as their predecessors' had been, a sour cloud of unfulfilled expectations emanating from accounting rooms everywhere as those messy, unpredictable variables stubbornly refused to yield to the new technological constants that were supposed to do away with the chaos of manned labour.

After another 70 years or so, enough time had passed for those doomed to repeat history to believe that their time had come.  Computerisation meant that the electricians and mechanics, with their specialised training, knowledge of arcane physics and militant unionism, were no longer needed.  The mechanical was becoming the digital.  Slowly, gradually, inexorably, the levers of day-to-day power were moving further away from men whose hands were covered in dirt to men whose hands had never known such indignity.  The blacksmith had become the metal worker, who had become the mechanic, who was becoming the engineer, and soon he would become the developer.  The revolutions were coming ever quicker; even the accountants has started to work more with charts than ledgers, and it was only a matter of time.  The digital revolution was here and the remnants of the old revolutions needed to be purged to make way.  The mine, the mill, the factory, these were legacies from a past time that had no place in the new order.  Again the keening wail, frustrated and helpless in the face of relentless progress, again the inevitable loss of the skills and the communities that formed around them. And as before 1 man did the work of 10 men, and those who were becoming chart-makers thought nothing of this except as it affected the colour of the font in their new digital ledgers.

Now, we stand as our predecessors did 30, 100, 200 years ago, a decade or more after the last revolution and staring the chart-makers squarely in the eye.  We are caught frozen in a moment of calm before we tip one way or another as the momentum of the world shifts to compensate for the weight of the now obsolete craftsmen that have been pushed to the side.

But in their absence a new breed of craftsman has arisen.  The architect, the graphic designer, the UX specialist, the technical writer - these are the modern stone mason, printer, fresco painter, scribe. Plant maintenance is now IT Operations, the mechanic is the developer.  Where once we made horseshoes, now we build containers, where before we listened to our machine to find their problem, now we step through their innards and debug them.  Just as in preceding revolutions, the change has opened as much opportunity for us messy variables as it has closed previous avenues.

Of course the chart-makers would claim this was their certainty all along.  Opportunity for all!  But this time the opportunities can be grasped by people using the very tools that have pushed their existing skills to the side and that's not the doing of those who would measure progress using graphs.  For graphs measure things, but that measurement has meaning only to those who find it meaningful.  To those who measure things not by lines or trends or bars, but integrity, dignity and human relationships, the chart-makers' obsession with these numbers is a measure only of the distance between them and the craftsmen.


The chart-makers glide through white corridors, cradling the magic screens that give them purpose and value, to glass-walled sanctums of design and certainty.  Outside these numerical monasteries the craftsmen toil, designing, sweating, thinking, building, drinking, testing, checking, laughing, smelling, living, messy variables that defy the digital constants to produce the magic that runs the screens.  The craftsmen know that the numbers are malleable, because the craftsmen make the magic that shows the numbers. 

Everything the chart-makers do is allowed only by the craftsmen.  Every trend-line, pie chart, scatter graph, presentation, calculation, prediction and report, everything they drive, everything they wear, everything they use, their entire world is predicated on the craftsmen, because the craftsmen are everywhere and their magic has seeped into every item, object, tool, process, and system. 

We don't make anything any more. We make everything.

But the divide between craftsmen and chart-makers is wide, too wide for either side's truth to bridge. 

So the chart-makers continue, bathing in the sterility of their quiet, calm, rational numbers.   And when the next revolution comes and the digital craftsmen feel the impotent rage of obsolescence, the chart-makers will point proudly to their charts and proclaim "We were right!".  The brave new world will once again forget the skills of the craftsmen from this age but the trend-lines will keep going up.


The charts don't lie.  They never lie, not to the chart-makers.

What's the Biggest Challenge You Face with SharePoint?



I recently had a conversation with someone that went something like this:

Him: "So what do you do then?"


Me: "I'm a Knowledge Management Consultant.  I'm currently helping a client implement SharePoint."


Him: "Oh, that's interesting.  We've just started using SharePoint and we're struggling with getting the right branding and styling on our publishing site.  Any tips you can give me on working with their CSS?"


Me: "Not really, I tend to work on the content management and collaboration parts, rather than the publishing side of it. But the Microsoft help material is very good and I can point you...."


Him [interrupting]: "What do you mean, you don't do publishing sites? I thought you said you were a consultant?"


Me: "I am, but SharePoint is..."


Him: "So you don't know what you're talking about then?"


The conversation went downhill from there, as my interlocutor almost, but not quite, accused me of lying about what I did and got increasingly irate and frustrated. In the end we parted company with him still muttering and me shaking my head ruefully.

Now you might instinctively think bad thoughts about my ill-tempered friend, but that would be a knee-jerk reaction.  He was clearly struggling with a complicated and powerful piece of software, and meeting someone who might be able to bring some light to the shadows must have gotten his hopes up, hopes which I promptly dashed.  It's only natural that he was frustrated, even if he didn't necessarily express that in the most constructive way.  What's more instructive about this encounter is that it represented a microcosm of the way an entire enterprise often feels about implementing SharePoint.


If you've encountered SharePoint before then the likelihood is that your experience hasn't been overwhelmingly good.  I've met more far more people with negative things to say about SharePoint than I have people with positive things.  It's like the England football team - depressing, confusing, poorly performing, promising lots and delivering little.  But like the England football team, SharePoint's individual components are good, yet the sum seems to be less than the whole of its parts.  To continue this analogy one stage further, the management just doesn't seem able to turn a collection of good things into a better coherent whole.

The question is: Why not?

Let's start an answer to that with the obvious point that SharePoint is large and complicated.  If you have SharePoint then you're going have Microsoft Office, which increases both the size and the complexity by a significant factor.  Office itself can be pretty difficult to get to grips with as a whole, when you've got both client and online versions, as well as lots of tools that weren't in the traditional Office package of a few years ago, like Sway, Planner and Video.  Then there's OneDrive, which is actually just a personal SharePoint site with a front-end, and Power Apps, Flow and Delve.  The sheer number of these apps is dizzying, and they all work together if you want them to, and each one is a whole book and training session on their own just to get comfortable with the basics.  Even programs as venerable and well-know as Word, PowerPoint, Excel and Outlook have lots of functionality that most users never know about or haven't got to grips with.  Then you add a powerful electronic document and records management system like SharePoint on top of all that and dear Lord, where on Earth do you even begin?

This alone is enough to put a lot of people off, and not just users.  Designing, implementing, training and supporting that kind of enterprise-level suite of applications, with its mind-boggling array of options, parameters and functionality, is not a job for the faint-hearted or workshy.  For users it can be even more daunting because they're not supposed to be the experts and usually have very little time to dedicate to learning these tools.

The biggest part of this problem is that often the people deciding to use SharePoint underestimate the investment of time and resources needed to design, implement and support it, and they seriously underestimate the investment of time and resources needed to train users. Many a C-level decision-maker has seen a demonstration, or worked in another company with a successful SharePoint implementation, or seen that it's a highly-recommended tool by a relevant professional body.  These are all valid reasons (although not sufficient on their own) for choosing SharePoint, but they're not valid reasons for thinking that SharePoint is easy, simple or quick to implement and maintain.  If you've seen SharePoint working well then you can't even begin to imagine how much work has gone into making that happen.

It's worth saying as well that when users struggle with SharePoint it's not always because it hasn't been implemented well.  SharePoint is so large that you can't even hire a consultant direct from Microsoft that knows all of it to a significant degree.  It's also not the most intuitive experience, which makes learning it harder.  Training users is always easier when an application has obvious signposts and markers for the users, because once they've got a rough idea of how things work they can generally find their way around and work out how to do things using these signposts and markers.  But there are plenty of areas in SharePoint where these signposts and markers are missing, often because a certain feature or parameter is "owned" by one application within SharePoint/O365, so you can only get to it from that application.  This means a lot more rote learning is required to know how to do things.  On an application as large and complicated as SharePoint this means that the learning curve is high, which acts as a significant barrier to adoption across a business. 

When you take these problems together - the size, the complexity, the difficulty learning it - it becomes easier to understand why my frustrated friend felt like he was banging his head against a brick wall.  He's most likely up against a deadline, he's faced with a suite of applications that is so large it's very difficult to know where to start, and when he does start the amount of learning to be done must feel insurmountable.

All of which leads to the reason that many companies struggle to have a successful implementation of SharePoint: It's not a one-off implementation, it's an ongoing process of training, learning and incremental advances for the entire life of the application.  

Every user needs to be trained, and not just with a 60 minute introductory session.  Every new starter has to be trained.  Existing staff have to have access to refresher training.  Training material needs to be updated as new functionality is released.  Content and working practises have to be analysed so they can be successfully migrated.  Deletion, retention and preservation policies must be decided and implemented from the very start.  Metadata must be applied to migrated content and added to all new content.  Workflows must be designed, created and added.  Security must be applied.  And throughout all this you have to deal with the change management aspects by engaging the users, communicating the plans and timelines, quelling fears, and listening to concerns.  If you can do all this, and still meet your success criteria then you'll have a successful implementation.

SharePoint is not an application, it's a long-term commitment of people and time.



(Note: A cardinal rule on this blog is that I never discuss current or previous clients.  Nothing from this post should be inferred about any company I've worked for; as always this is a general discussion about issues that we find in our industry.)


Sunday, 5 February 2017

The Basics: 12 Steps to Writing a Great Knowledge Base Article



Knowledge Base (KB) articles are normally technical and as such in the realm of the technical writer.  Where an FAQ might encourage you to try a new product or feature, a KB article helps a user get past a problem when they're already using that product or feature.  So if FAQs represent "sales self service", KB articles represent "support self service".  

With this in mind, you should focus your initial efforts on writing KB articles that will answer the most asked support questions.  This will provide the greatest return on investment for your documentation.  Once you've built up a library of articles, you should try to move to a position where new KB articles are written in response to incoming customer questions.  Ideally, if a customer asks a question once, and the answer isn't publicly available, you'll publish a KB article answering that question within a short period of time

But how do you write a good KB article?  Well, the basics of writing good documentation don't change, but there are a few things which are more important when writing KB articles.  Let's got through them below.

1. Know the subject

First and foremost, don't publish an article unless you're certain it's correct.  This applies to experienced staff who think they know exactly how the product works just as much as it applies to less experienced staff.  As an example, I once wrote a KB article on the possible permutations of accounts and permissions that could be setup for a web application and IIS, but I'd misunderstood the scope of the question.  The result was a rewrite that took some time because the people who understood the technical side were difficult to get hold of, and more importantly it confused a couple of customers, which was the worst possible outcome.  This leads directly to #2.

2. Proof read for technical correctness

Get 2 different people to proof read it if necessary.  There's no shame in asking for the input and oversight of people who are more technically qualified or experienced than you.  As a technical writer you are expected to understand technical issues so you can communicate them, but you're not expected to know all of the technicalities of a product better than anyone else.  That's why you have architects, designers, administrators, installation experts, etc.  Use them.

3. Iterate.  Then iterate.  Then iterate again.

Preferably find someone who doesn't know how to perform the actions you're explaining and ask them follow the instructions through.  If they don't understand it first time, or they ask about an ambiguity, alter the article until it's clear and unambiguous.  This is not a negative step, it's a necessary part of writing a good piece of technical documentation.  A KB article can deal with complex issues that can be even more complex to explain, so the first draft of a KB is unlikely to be the last. Write, test, alter, repeat.

4. Don't overestimate the reader's knowledge

AKA Know Your Audience.  If you're writing for a data entry operator then take the time to explain things that seem obvious to you.  Remember, if you weren't knowledgeable enough about the software to write technical documentation about it, you wouldn't be writing KB articles.  You know more than your target audience so walk them through things if necessary.

5. Don't underestimate the reader's knowledge

AKA Know Your Audience part II.  If you're writing for a System Administrator then try to avoid the whole "teaching your grandmother to suck eggs" thing.  It's a tricky balancing act but if the target audience is (supposedly) technically competent or highly knowledgeable then they won't thank you for wasting their time or making them feel stupid.

6. Make it modular

If you find yourself walking through the same process in more than one KB article, then write a separate article that just deals with that process and link to it in future articles.  This saves you time and helps the user by not cluttering up articles with information that's duplicated elsewhere.

7. KISS

The old "Keep It Simple, Stupid" acronym. In the case of KB articles, this means that you should try to capture one task or process in one article.  Don't try to cram too much in, and don't shy away from writing a series of articles that deal with the distinct stages of a complicated process.  At the start of each article in the series tell the reader that they should be familiar with the information in the preceding articles before continuing.  This allows them to feel that they are making progress and allows you to write self-contained articles that just deal with the problem in hand. 

8. Step-by-step

Don't explain a process in a paragraph.  Use a numbered list, and make 1 numbered point = 1 step.  As a rule of thumb, if there is more than 1 action in 1 numbered point then turn it into 2 numbered points.

This goes hand-in-hand with points 4 and 5 about knowing your audience.  If you're writing for System Administrators who know the product, don't be afraid to write:

"1. Log into the application and navigate to screen x"

Equally, if you're writing for potentially inexperienced users don't be afraid to write:

"1. Log into the application."
"2. Navigate to screen x.  In a default setup this will be located at System > Parameters > screen x"

Generally paragraphs should be used to explain something from a conceptual perspective and numbered lists should be used to explain actions and steps.


9. One Step, One Screenshot

If you write an article with 10 steps, use a good screenshot for each one if it will help the user.  A picture tells a thousand words when you're trying to understand something new.  Users aren't short of the bandwidth needed to download a 20kb png file and I know that the use of screenshots is controversial, but don't preclude them on a point of principle.

10. One Screenshot, One Lawsuit

I can't say this enough: Check your data.  I have seen a KB article published by a colleague who'd taken screenshots using a live database, and those screenshots included identifiable information about customers.  If you have access to live databases, or, as if sometimes the case in development teams, a customer database provided for the purposes of testing, then check, check and recheck your data.  If in doubt, create dummy data, and if you can't then obfuscate any data or consider not using screenshots.  Using live or customer data is a one way ticket to a lawsuit for your company and quite possibly the sack for you.

11. Quality, not Quantity

Yes, it looks great if you bang out 20 KB articles in an afternoon, but it doesn't look so great a week later if 19 of them have been the cause of support tickets.  You're supposed to be helping support, not making more work for them.  You can't rely on a proofreader to weed out every mistake, because it may be that you're the person who's supposed to be an expert on whatever it is you're writing about (this is especially the case if you're not a technical writer and you're adding KB articles).  Writing KB articles is not a fast and easy way to look good.  It is difficult to write well, and even more difficult to write well at speed.  Take your time, think about what you're doing, focus on getting it clear and correct.

12. Spell check is not optional

If you're a technical writer you'll know this, but if you're not then hear this: You can't spell.  Seriously.  Technical writers do this for a living and we spellcheck everything.  Learn to love Word and its spell checking, grammar checking, and little squiggly lines.  These is no excuse for a spelling error in a KB article and it will make you look incompetent.  It will also make your company look incompetent and reflects badly on everyone.  Don't be the person who makes your users wonder how on Earth your company can write decent code if they can't even use a spellchecker.

KB articles are a great way to take the load off support and give customers the power to fix their own problems.  Get it right and you'll find the rewards far outweigh the costs.
 

Saturday, 28 January 2017

A List of Style Guides for Writers



Style guides cover a multitude of areas and it can sometimes be difficult to separate the purely writing-focused guides from the general UI/UX guides.  This is not surprising, considering how much UI/UX, technical writing and comms/marketing are starting to coalesce around the central idea of user focused design. But if you're not working in that environment, or if you are but you still want some purely writing focused resources, it can be a little difficult to sort the wheat from the chaff.

With that in mind, I've put together a list of some useful guides below:


Online


  • MailChimp - One of my absolute favourites because they focus on the likely user mood at the point of the interaction, and tailor their writing accordingly.  This is a relatively unknown style guide, but it should absolutely be one that you spend time looking through.
  • Mozilla - A (relatively) short and to the point style guide that focuses on developer documentation.  If you write for developers (SDK, API, etc) then this is an excellent resource.
  • Apple - As you would expect from Apple, this is not the longest style guide but it is proscriptive.  One of the most useful features is the table that converts "developer speak" to "user speak", so for example "focus ring" for an Apple developer is Highlighted area" or "area ready to accept user input" for an Apple user.
  • Google - This focuses on writing for a worldwide audience and as such is concerned with clarity and simplicity above all.  If you're writing for a geographically diverse audience, especially one which is not highly technical, then this guide will help you a lot.
  • GDS - The Government Digital Service guidelines for the UK Civil Service.  Not as easy to navigate as many guides, because topics are provided in an A-Z format rather than curated into groups, but contains a lot of information and is recommended if you're writing in UK-English. (The lack of curation is odd; GDS people are normally very big on user-focused design, and this...isn't.  But if you can get past that, the information contained is often difficult to find elsewhere.)  
  • 18f.gov - The American equivalent of the GDS style-guide, this is focused more on US-English and the needs of federal/state public bodies, as you would expect.  But it's comprehensive, well-written and very good on grammar and "correct" writing so even if you're not writing in US-English, it's still a very useful resource.  And if you ARE writing in US-English, it's indispensable.
  • Microsoft - Microsoft provide one of the best known and popular style guides in print (see below) but this resource is far too valuable to miss off the list.  The link takes you to a page with just a single dropdown, from which you can download a PDF style and language guide for just about every language you've ever heard of, and many you haven't.  French, German and Russian are fairly obvious, but how about Khmer, Igbo and Xhosa (the African language with the clicks)?  If you write in any language other than English then this is probably the single most valuable guide on this list.

Print

  • The Elements of Style - The classic book on how to write.  The focus is not on software documentation (unsurprisingly, as it was first published in 1920), but not having a copy of this is like being a quantum physicist who's never read Einstein's papers on relativity.  Some things are just fundamental to your profession.
  • The Economist Style Guide - Another without a software focus, and the first edition was published 30+ years ago, but if you want to write clearly and - according to the Economist - with a little flair, this is the book for you.  Its best feature is undoubtedly its effort to focus on real-world examples that are universal in application without being generic to the point of mere common sense.
  • The Chicago Manual of Style -  If you've only heard of 1 style guide, the chances are it's this one.  Now on it's 16th edition, it includes specialised sections on writing for digital technologies, including writing with XML.  If your office doesn't have this on its bookshelf, it should be because you've got the next guide on our list.
  • Microsoft Manual of Style - A slightly more specialised guide than Chicago, but no less useful for it (and probably more so if you're a technical writer).  Unless you write software for Apple and only Apple, this guide will show you why so much software documentation has the style and tone that it does.
  • The IBM Style Guide - One of the most comprehensive style guides available for the modern technical writer.  It is particularly strong on Information Architecture and content design, but don't let that fool you: this is a standout resource for all writers.
  • Developing Quality Technical Information - Another IBM publication and not strictly a guide, but so useful that leaving it off the list for that reason would be petty.  There is significant overlap with the IBM Style Guide, but this focuses more on training you and less on being a reference work.  Unless you're an acknowledged expert in technical documentation, you'll gain a great deal from this book.
There are lots more style guides out there. If you have a favourite that's not in the list then tell me in the comments and I'll add it in.

Saturday, 7 January 2017

The Basics: Diaritics and ALT Codes

 Text with colourful accents
This post was inspired by Lori Kaufman's post on How To Geek about adding symbols.  She writes a regular column on how to do useful things with common applications, and it's very much worth following.

It might seem odd to label a post about diacritics and ALT codes under "The Basics" when most people don't even know what the word "diacritic" means, nor have they used ALT codes.  But you've seen diacritics, and quite possibly used them, even if you don't know what they are, so you definitely need to know how to add them when you're writing.  And the easiest way to add them is with ALT code.


So, what is a diacritic?

(Warning: If you've studied linguistics, philology or a European language to any extent you can probably skip down to the part about how to add them to your documents.  For everyone else, read on.)

A diacritic is a symbol or glyph added to a letter, primarily to show how that letter is to be pronounced in the context of the word. If you ever studied French at school you'll be familiar with accents such as
´ (acute) or ` (grave); accents are a type of diacritical mark. For those of you with a more Germanic bent you'll be familiar with the ¨ (umlaut), but even if you've never spoken a language other than English you should still be familiar with the diacritics in façade and naïve (called a cedilla and diaereses respectively).  A good example of how a diacritic changes the pronunciation of the word is "rèsumè" (also known as a CV), where only the accents distinguish it from "resume" (to begin again after a pause).

There is plenty of material available on the use of diacritics if you want to delve into it a bit more (and please do, they're fascinating), but what we're concerned with here is how to add these marks when using standard technical communication tools. 

Adding Diacritics to your Content

We'll focus on 3 types of documentation tool: word processing, content authoring, and wikis.  Between them, these cover the vast majority of types of tools that are used for professional technical communication (we're ignoring things like JavaDocs or Swagger on the basis that code doesn't have accents). There are a lot of different tools out there, so I'll focus on the following examples:
  • Word (word processing)
  • FrameMaker (content authoring)
  • Confluence (wiki)
Each of these tools provides built-in fonts and/or glyphs that cover diacritics, as will any decent word processing or content authoring tool.  Wikis are often a bit different because they have more or less of a GUI or WYSIWYG interface.  As a general rule, the less GUI, the less built-in support you'll get.  Confluence does have built-in diacritics, but once we've covered the 3 tool examples we'll look at a more general method for typing diacritics.

Word

Word - of course - provides pretty much complete support for every conceivable diacritical mark, of which, when combined with every letter of every currently used alphabet, there are a very large number indeed.  For common words like "facade", Word will simply autocorrect them, in this case to "façade ".  That will probably cover you for most English words, simply because English has only a small number of words with diacritical marks.  But it's always better to know how to do things manually if you have to, so in Word go to Insert on the ribbon and on the far right hand side click the down arrow next to Symbol.  On the small dropdown that appears click More Symbols to open the Symbol dialogue:


(For you keyboard shortcut aficionados, you can also access this dialogue with ALT+N+U+M)

By default, this dialogue will open with a Font value of (normal text) and a Subset value of Basic Latin. This will display the familiar Latin alphabet and if you scroll down you'll find lots of diacritically marked letters, grouped into language families.  For example, the French diacritics are together, the Slavic ones are together, and so on.

Select the Font you want, if it's different from the font you're currently using, and scroll down the list.  You will almost certainly find the letter and diacritic combination you want, whether it's the familiar Latin-derived alphabet, Cyrillic, or Greek.  If you want to know the official name of a symbol, click the character and the Unicode name will be displayed under the Recently used symbols box.  In the screenshot above, I've selected "Latin Small Letter A With Tilde".

FrameMaker

FrameMaker also provides a way of adding diacritical marks, but in a far smaller range than Word. The list of supported diacritics is as follows:
  • ´ (acute)
  • ` (grave)
  • ˜ (tilde)
  • ¨ (diaeresis)
  • ˆ (circumflex)
  • ^ (caret)
  • ° (ring)
  • ¸ (cedilla)
(For those of you who did a little German at school, a diaeresis is identical in formation to an umlaut, although they alter the word in slightly different ways).  FrameMaker allows you to enter these supported diacritics by using an Escape key sequence.  For example, to type an è (an e with a grave accent) you press the Escape key, then the ` (left quote) key, then the e key.  Unlike CTRL+ALT+DEL where all of the keys need to be pressed at the same time (i.e. in combination), in FrameMaker you need to press them one after the other (i.e. in sequence).

You can find the list of FrameMaker-supported diacritics and other symbols here.

Confluence

Confluence lies somewhere in the middle.  It provides more diacritics than FrameMaker, but substantially less than Word.  Like Word, you can select your diacritic from a modal panel rather than with a keyboard sequence and the following shows all of the diacritics and symbols that are available to select:
 


These are good examples of the type of functionality you'll find around diacritics in modern tech comm tools.  They range from the comprehensive to the minimal, but they're still better than some applications that provide no functionality at all.



What's the generic way of entering diacritics?

Different applications have different methods for entering diacritics, and different native support, which means more learning and a patchy experience.  So for those of you looking for a generic way that will work in any application, you need ALT codes.

ALT codes are a method of writing special characters that aren't represented on the keyboard.  Pressing the ALT key (or Option on a Mac) and a number on the numeric keypad will display the special character.  For example, ALT+138 will type è, an e with a grave accent.  You can find a complete list of the basic ALT codes here.  Note that you need to use the numeric keypad - the square of numbers on the right hand side of a standard keyboard - to type these in.

However, there is a little more to it than that, because some ALT codes do the same thing.  If you type ALT+0232 you'll get the same è that you do with ALT+138, which seems...odd.  What's going on?


An Incredibly Brief History of ALT Codes

Historically, ALT codes were used in early Microsoft computers to access the character set that couldn't be typed using the standard keyboard.  The early DOS machines were based on the IBM architecture which used a character set called code page 437, and the ALT codes for these are ALT+0 - 255.  In this character set ALT+138 gives you the è.  Because this character set comes from the architecture and not the operating system it's known as the OEM-encoded (Original Equipment Manufacturer) character set.  (Originally IBM used the ISO 7-bit character set that went from 0 - 127, but the ISO extended it to 8-bit to provide space for non-English characters, which led to the classic 256 character set - known as the extended set - that is so commonly used.) 

But 256 characters is quite limited, and other architectures slowly emerged as well, so Microsoft decided to use their own, additional character set, which is known technically as Window's ANSI/ISO Latin-1/ANSI Extended ASCII.  This provided additional space for more codes by prefixing them with a 0, and in this Windows-encoded character set ALT+0232 will produce è. 
You can download an ALT code cheat sheet in PDF format here (Warning: link goes straight to the PDF) that includes both the OEM- and Windows-encoded ALT codes, grouped together in useful sections rather than a numeric list. 

Unicode

In modern incarnations of Windows the Unicode 16-bit character set is used, as it's the global standard, but the original OEM- and Windows-encoded character sets are still there and the ALT codes for those still work.  

Because the Unicode 16-bit character set is vast (see here for some figures, but as a spoiler there are over 70,000 encoded Chinese characters alone), remembering even a tiny fraction of the codes that represent them is beyond mere mortals.  Luckily Windows includes a Character Map that will show you all of the available characters and tell you what their ALT code is.  To access this pre-Windows 10, type Character Map in Windows search.  In Windows 10 the Character Map is - for reasons known only to Microsoft - hidden away, and you'll have to launch it manually.  Hit Win+R and enter charmap, and up it'll pop:


As you can see in the bottom left, the Unicode value is shown for the selected character.  To use this as an ALT code just use ALT+[the four digits], in this case 0021.

If you switch on the Advanced view checkbox you'll also be able to choose a character set, group by types of ideograph and, most importantly, search for a character.  This is very useful when you've got so many characters to search through.  In the example below I've search for "grave":


The Character Map is probably the single easiest way to search for and find the ALT code you need, and will allow you to handle any diacritics with ease.

The history and technical specification of character sets, and how they're used, is a vast topic.  What I've mentioned above is the briefest outline of a long, complex and thoroughly interesting subject.  If you're at all interested in the topic then these links are good jumping off points:
If you know of other good resources about character sets and encoding for the educated non-developer, put them in the comments.