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 codes.
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.
The lovely people at GDS, in association with Write the Docs, put on a great one day mini-conference, Agile the Docs, on 5th December in London. I was asked to present on whether documentation was in the definition of done and I was more than happy to oblige.
Without further ado, here are the slides I used, and here are the notes (I haven't done a lot of editing or formatting on the notes; the links below contain everything I talked about in a more comprehensive - and formatted - way).
If you're interested in learning more about this topic then check out the following articles:
Thank you to Trisha, Rosalie, Jen and Lydia from GDS, and Kristof from Writer the Docs. You organised a short, sharp, interesting conference with interesting and diverse speakers, in a good location, at a sensible time, near a decent pub and a tube station. Top work all round.
On a side note, the BRDC were having a benefit lunch/gala thing in the same conference centre we were, and this was parked outside:
It's an impressive machine in the flesh. And I saw Nigel Mansell in the corridor, which was pretty cool. He looks exactly the same as he did when he won the F1 championship 24 years ago (except for the 'tashe, which went a few years back.). Exactly the same. Either he's aged very well or he looked a lot older than his years when he was an F1 driver.
Anyway, Agile the Docs. Really enjoyed it and looking forward to attending the next one. If you've got questions or thoughts on the presentation use the comments below or tweet me @agiledoc.
Confluence is a super-charged wiki from Atlassian, the same company that makes the popular issue tracker, JIRA. As you'd expect with a normal wiki, its most popular function is as a knowledge base, documentation hub and FAQ location, but due to it's tight links to JIRA (and other Atlassian products) it's also used for showing sprint reports, burn downs, burn ups, work in progress, and lots of other reports using data taken straight from JIRA.
In this post we're going to focus on the traditional wiki usage: documentation and knowledge management, and specifically some do's and don'ts when moving existing documentation and knowledge assets into Confluence. Some of the points below are specific to Confluence, some are best practise whenever you're moving knowledge from one place to another, but they're all born of experience and hopefully they'll help you avoid some of the pitfalls.
The most important points first:
- If you're a technical person, get a content person in before you move anything. They'll spot issues you won't.
- If you're a content person, get a technical person in before you move anything. They'll spot issues you won't.
I'm more of a content person, and having some technical people (i.e. developers) around helps immensely. A developer's first thought is always "How can I do this through code?", which means they're much better at spotting situations where a batch file or a regex or some CSS will make everything a lot quicker and less manual. When I was looking at moving documentation from some internal wikis, it was developers who helped me find the appropriate export functionality and worked out whether I could take that format and import it into Confluence, potentially saving me weeks of work.
Which brings me neatly on to:
- Automate as much as you can.
This means using export tools in your current location (e.g. wikis, CMS, document repositories, etc), and also Confluence's excellent built-in Word import functionality. There is a Universal Wiki Converter which is not supported by Atlassian because it's a 3rd party tool, but the fact that the link for it takes you to a place on the Atlassian domain should tell you they think it's useful. It doesn't work on every wiki, but if it does work for your wiki it will save you a lot of time. If instead of, or as well as, wikis you've got lots of Word documents to import, the Confluence Word importer is brilliant. It's really good at importing formatting and layout, as well as features like tables, images, links, headers, footers and diagrams, and it's really quick to boot. Oh, and it will create new pages every time there's a heading in your document, if you want it to, even down to being able to set the level at which new pages are created (e.g. it will create new pages every time it finds a Level 1 or Level 2 heading, but ignore any other heading levels). The Word importer has saved me huge amounts of time.
Before you start importing things:
- Plan your space structure before you move things in.
It's pretty annoying having a structure set up and working only to find it doesn't scale to accommodate what you're transferring and you have to move things around again. This is where a content person is really helpful if you're a technical person. Content people are good at the structure and layout of large bodies of information, and we'll help you analyse the user needs and get it right. Confluence's space and page structure is deceptively simple because this simplicity means it's very easy to create monolithic spaces with one massive list of alphabetically ordered pages. But people don't connect information alphabetically, so creating a space directory, page trees and label taxonomy using the guiding principles of good information architecture will make it much easier for people to navigate.
- If multiple people are bringing stuff in, agree on common naming conventions, page structure, and labels.
There's no getting away from the fact that if a team of technical communicators will all have slightly different ideas about conventions and structures, then a motley crew of various resources will all have very different ideas about conventions and structures. Even if all the people importing are technical communicators, and especially if they're not, set agreed standards for page naming conventions, page structure and labels BEFORE anyone imports anything. Otherwise it'll require a massive remedial exercise later on to standardise everything, or if this isn't done, your Confluence instance will be a mess.
- On the subject of labels, use them to say where a Confluence page came from, e.g. wiki name, shared drive, SharePoint, or wherever.
If you've never gone through this kind of process before this might seem superfluous, but believe me, it's not. No matter how careful you are when you're importing, you or someone else will want to check the original source because "it doesn't look right" or "I'm sure we used to have more information on this in the old system".
And while we're talking about it:
- Keep your old repositories for at least 6 months, just in case.
Transfer them to a portable hard drive that an admin locks in a secure cupboard if necessary, but don't "move and delete" because you'll regret it (even if no-one needs the back up you'll always be fretting that someone will need the back up). If after 6 months (or whatever time frame you're comfortable with) you haven't needed the back up, get rid of it. But in the meantime, keep them so that you can answer queries about "it doesn't look right" or "I'm sure we used to have more information on this in the old system" (see above) and so that you can do "idiot checks" to make sure you've got everything. Pro tip: Every time you import something, move the original to a new location that mirrors the structure of the original location. That way you can be sure everything's been imported. If you can't realistically move it, mark it with (something like) an underscore at the beginning of the title. This is also helpful when multiple people are importing things as it stops people importing the same thing twice.
Despite the fact that you're keeping your old repositories for a while:
- Bring as much metadata over as possible, especially who last edited [whatever you're importing] and when.
When you create a page in Confluence, your name is sat under the title as the creator. This isn't useful for people who want to ask questions of whoever created the original content. Pull the metadata from wikis or documents (manually if necessary) and add it to the page, preferably in a default location such as just under the title.
Having said that:
- Consider adding smaller documents as attachments rather than extracting the contents.
This will greatly reduce your import time and allow you to turn off your old system much quicker. You can then turn the attachments into actually pages over time if you want to. I wouldn't advocate using Confluence as a document library because really it's very poor at that. But in terms of speed, you can drag and drop multiple documents at once into the Attachments page (or the Attachments macro) and if you're pushed for time to remove things from the old system this will work as a temporary measure.
Finally, a couple of "human" issues:
- Manually porting things over can be boring and a lot of people won't do it right because of this. Only get people who really enjoy doing this kind of repetitive, finicky work, otherwise you'll spend huge amounts of time correcting the work of people who got bored 10 minutes after they started.
- As soon as you can turn off the old systems, do it. Or at least restrict access to them. People are creatures of habit and lots of them will keep using the old systems until it's literally not possible,
- It's going to take longer than you thought. Take a deep breath, settle in for the long haul and don't get downhearted. You can and will do this, and it can and will be a success.
