Category Archives: Technical

26 tips for planning, writing and editing a glossary

By Hazel Bird

an open bookGlossaries are commonly found in a huge variety of publications, from textbooks to technical reports and from encyclopedias to essays. A good glossary can serve a number of purposes that benefit both writers and readers:

  • provide a quick reference to key concepts
  • avoid the need to duplicate definitions of key concepts in multiple locations
  • increase the accessibility of a text and thereby avoid alienating less knowledgeable readers
  • enhance the experience of more knowledgeable readers by avoiding cluttering a text with what may (to them) be basic definitions
  • help groups of co-authors to write consistently on a topic.

But a good glossary is too often an afterthought – thrown together at the end of the writing process with little consideration of how it can help to underpin a text and amplify its authority.

This post looks at how to plan, write and edit a glossary that will enhance a text and be helpful to readers. But first, a post on glossaries would be remiss if it didn’t include its own glossary:

DefinitionThe part of a glossary that tells readers what a term means.
EntryOften used to refer to a term and its associated definition as a whole.
GlossThe verb form of glossary. If you gloss a term, you provide a definition of it.
GlossaryA list of definitions of technical terms used in a text.
TermA word deemed to be of sufficient importance or complexity to require an entry in the glossary.
TextThe larger body of words of which the glossary is a part (eg a book).

It’s worth saying that although the stages below can be a helpful way of dividing up work on a glossary, it makes sense to keep all the stages in mind at all times. For example, it doesn’t hurt to decide your preference on capitalisation during the planning stage. And, equally, there’s no point developing a comprehensive plan if the writer(s) and editor(s) then ignore it!

Planning your glossary

A good glossary is based on a well-planned strategy. Questions to consider when planning a glossary include the following:

1. Why are you considering providing a glossary? Would the text genuinely benefit from a glossary as an added help to the reader? Or would the glossary primarily serve to cover up uneven, unclear or incomplete writing that would be better amended before seriously considering how a glossary would fit in?

2. What level(s) of knowledge do you expect your readers to have? Do you need to gloss basic terms or only the more advanced?

3. What level of detail do you want your definitions to have? It can help to set a nominal word or line limit.

4. If your text has multiple chapters, will you have one central glossary or chapter-specific glossaries? If you prefer a central glossary, do the chapters use the same terminology or will any revisions be required to standardise terms that will appear in the glossary?

5. If your text has multiple authors or topics, how will you ensure consistency between their glossaries? Would it be helpful to provide a few sample glossary entries (taking account of the suggestions for writing and editing below)?

6. Will the glossary be allowed to define abbreviations or will these appear in a separate list? For example, if your text talks about JSON, do you want to have (a) a glossary entry that provides the full form (JavaScript Object Notation) and then talks a bit about its use in software development, (b) an entry in a separate list of abbreviations that simply provides the full form or (c) both?

7. Will cross-referencing between glossary terms be allowed (or required)? For example, the glossary of glossaries at the start of this post uses italics to cross-reference to other entries. This lets readers know a term is explained elsewhere in the glossary (and often means you can be more economical in your definitions).

8. Where will the glossary appear and how will readers access it? Common schemes include: (a) simple standalone glossary with no links to the text, (b) standalone glossary with hyperlinks and/or special formatting (e.g. colour or bold) on glossary terms in the text and (c) glossary entries on the same pages as their associated terms (common in textbooks). Which would be most suitable for your text?

9. How will readers know your glossary exists? Will you put a note at the start of the text (or even at the start of each chapter or section, if your text has subdivisions)? What will be the best balance between making information easily accessible and avoiding clutter? You can’t assume that readers will understand that bold (for example) means that there is a glossary and that the bold word is glossed within it – you have to tell them what the bold means.

Writing your glossary

Once you have a solid plan to work from, you can actually start writing your glossary (or ask your contributors to submit entries to you). Following are some do’s and don’ts of glossary writing:

10. Do consider how your terms are actually used in the text. There’s no point having a glossary term for ‘information architecture’ if the text only ever refers to ‘architecture’.

11. Do use parallel structure. For example, will you start definitions with ‘X is an …’ or just ‘An …’? This issue is connected with presentation too: usually, the longer form is only necessary if you plan to run the glossary terms into the definitions. For example:

Agile  A method of software development that occurs in stages, with the product evolving as the project progresses. (Separated style)

Agile is a method of software development that occurs in stages, with the product evolving as the project progresses. (Run-on style)

12. Do think about the grammatical forms of words. For example, it might look inconsistent to have a definition for ‘coder’ (noun) alongside one for ‘developing’ (verb). Unless there’s a good reason, it might read better to choose either ‘coder’ and ‘developer’ or ‘coding’ and ‘developing’.

13. Don’t use the word in the definition – usually. Sometimes it works, where you decide to explicitly re-state the term in the definition for grammatical reasons (as I did above in my definition of ‘gloss’). But usually it’s bad practice as it assumes knowledge on the part of your readers that they might not have. For example, you might include the following definition:

software development  Using computer code to develop digital applications and infrastructure.

Here, you’d only really have glossed ‘software’ and you’d be assuming your readers know what ‘develop(ment)’ means in the context of computing.

14. Don’t make the definition so complicated that the reader has to look it up to understand it. (Or, if you need to use technical terms, consider defining them elsewhere within the glossary and including cross-references – see point 7 above.)

15. Don’t include Wikipedia content (or similar) – anyone can do an internet search for a generic Wikipedia definition. Glossaries add value for the reader by framing each term in a way that is nuanced to reflect the content of your text.

16. Don’t quote other sources in your definitions, unless they offer uniquely relevant perspectives or you have a special reason for doing so. This can reduce the sense of authoritativeness of your text.

17. Don’t repeat definitions from the text. Readers will be frustrated if they go to the glossary in search of further explanation and just find what they’ve already read.

a cluttered, compact office environmentEditing your glossary

Glossary editing often takes place over multiple stages. First, the person who wrote the glossary (or who is collating it from multiple contributors) checks that the content is suitable and that there are no glaring holes or inconsistencies of approach. Then, another person (often a copyeditor or proofreader) conducts a more zoomed-in check to sculpt the glossary into its final form. Each will likely need to look at the following points to some degree:

18. Does the glossary adhere to each point of the plan? If not, is the divergence acceptable (perhaps something has changed since you created the plan) or do you need to adjust the entries?

19. Is the coverage logical, consistent and comprehensive? For example, have all terms of the same type been included? (So, if you’ve glossed XML, you’ll probably want to gloss HTML too if your text uses both terms.) Are there any often-used terms that are not glossed but should be? If one of the glossary’s functions is to gloss little-used terms to avoid cluttering the text with explanations, have all of these been identified?

20. Will your alphabetisation be intuitive to readers? For example, will your readers expect to find a general explanation of the syntax used in computer coding under ‘language’ or ‘programming language’?

21. Do you need any ‘see’ entries? If readers might look for the same term under two different phrases, you could choose to include both. For example, you could have a definition of the term ‘language’ but also cross-reference to it further down as follows:

language  Words and other notation used according to a pre-defined structure to create computer programs.

programming language  see language

22. Is every term in the glossary actually used in the text? See also points 10 and 12.

23. Have the glossary terms been indicated in the text where applicable (see point 8)? And are you doing this on every occurrence of each term or only (for example) at first use in the text or chapter?

24. Is the punctuation consistent? For example, will your definitions end with a full stop? This may depend on the length of the definitions. Single-sentence glossaries can end with nothing, but multiple-sentence glossaries usually look best with full stops. If you have a mixture, it’s best to be consistent and include full stops for all of them.

25. Is the capitalisation consistent? Will you capitalise all of your glossary terms (eg ‘Debugging’ and ‘Python’) or only proper nouns (eg ‘debugging’, but ‘Python’)?

26. Does each definition read well and follow whatever spelling and other stylistic conventions have been used in the main text? When they think about what goes into editing a glossary, many people jump straight to this point. But, in reality, it’s just the last item in a long list of other considerations.

Planning, writing and editing a good glossary is a complex and time-consuming process. Throwing together a glossary at the last moment is a wasted opportunity and may even detract from the reader’s experience – for example, by raising expectations that are not met (eg because the glossary is of poor quality and isn’t tailored to the text) or creating frustration (eg if the glossary is difficult to access or navigate, or equivalent terms are not glossed).

Thinking about your glossary from the start of the creation process will make it an integrated and cohesive part of your text, and enhance the text’s value and authority for your readers.

Hazel Bird standing outside by a wallHazel Bird is a project manager, copyeditor and proofreader who has happily edited glossaries that followed all of these tips and others that followed none. She regularly works on computing books (hence the examples above) but also edits widely across business, public sector and academic publishing.

 


Have you seen our recent focus paper by David Crystal on why it’s worth using a professional editor? It’s one of CIEP’s many fact sheets and focus papers for editorial and publishing professionals.


Photo credits: Open book by by Jonas Jacobsson; Software development by Hack Capital, both on Unsplash

Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.

What’s e-new? The efficient guide to Word

By Andy Coulson

This issue of The Edit has a theme of working efficiently, so let’s take a look at how we can persuade every editor’s favourite tech tool to work efficiently.

1. Keyboard shortcuts

Keyboard shortcuts are a great little time saver. Think about what you do when you use a mouse – you move it about to try to line up a pointer on a (small) target. You then click and, depending on what you want to do, perhaps repeat this two or more times to get to your command. But with a shortcut you press two or three keys together, and away you go. ‘How-To Geek’ has a really good list.

You don’t have to accept Microsoft’s default choices, either. If you go to Options > Customize Ribbon you’ll see an option at the bottom to customise keyboard shortcuts. This allows you to set up shortcuts for any commands. You can also allocate shortcuts to macros (see below).

2. Styles

Styles offer you a way to quickly format elements of the document. However, they can be a bit fiddly to use. In Word 365, the styles appear in the Home ribbon, as well as in the Quick Access Toolbar at the top. Often you’ll find you use the styles already in the document, and you simply apply them by putting your cursor in the block of text you want to style and then clicking the style name.

But, what do you do when a client says ‘make file A look like file B’? Word has a mechanism to copy styles between documents, but it’s well hidden. You can add the Developer tab to the ribbon, which you do by going into File > Options > Customize Ribbon and selecting ‘Developer’ from the list on the left. Make sure ‘Main Tabs’ is selected at the top of the list on the right and then click ‘Add’.

In the Developer tab, click on ‘Document Templates’, and then ‘Organizer’ in the ‘Templates’ tab of the pop-up box. You will see two lists. The one on the left should have the file name of your current document underneath. On the right-hand one, click ‘Close File’, and this will clear the list, then change to ‘Open File’. Click on it and select the template or document you want to import from. You can then simply select the styles you want and click the ‘Copy’ button to import these to your document.

3. Wildcards

If you use Find and Replace, learning to use wildcards will transform your searching. These allow you to look for patterns rather than specific words. For example, ‘?ed’ tells Word to find ‘ed’ preceded by any other single character, so it would find ‘red’, ‘bed’, ‘Red’ or ‘Bed’ and so on. This can get complicated, but it can also be a real time saver. One of my favourite applications is cleaning up question numbering in textbooks where I can’t use auto-numbering. Here, searching for ‘([0-9]{1,2})\)^s’ and replacing with ‘\1^t’ would change one- or two-digit numbering like this: ‘1.<space>’ to ‘1<tab>’.

There are an awful lot of options, and one place to find help on these is Jack Lyon’s Wildcard Cookbook for Microsoft Word, which is available as a PDF ebook. I have it open in my ebook reader most of the time I’m editing in Word. Geoff Hart’s Effective Onscreen Editing also has a chapter on making the most of Find and Replace.

4. Macros

Macros are short programs that build on the capabilities of Word. They often link together a number of functions within Word to achieve a more complex task, be that something which finds information about the document, changes what you have selected or makes global changes.

Many of you will be aware of Paul Beverley and his macros, and I can’t suggest a better way in to macros than Paul’s Macros by the tourist route. This is a really good introduction to using macros, and will lead you to Paul’s amazing macro library. Once you get into using these you can really start saving time on your work in Word.

Among my favourites are DocAlyse, which runs a range of tests on a document to flag the types of issues it may have; WhatChar, which identifies any character; SpellingErrorLister, which creates a list of potential spelling errors; and HyphenAlyse, which identifies the frequency of hyphenated words (and their non-hyphenated equivalents) and checks common prefixes.

The CIEP has also produced a fact sheet about getting started with macros.

5. Add-ins

Add-ins go a step further than macros. They are programs that work within Word to add more functions. Many of you will have heard of PerfectIt, and this is a good example. PerfectIt will check consistency in the document in a way that Word’s tools simply can’t. You can install stylesheets to suit particular clients (or create your own). I recently had a job using Chicago style (CMOS), and through the forums (thanks, Hilary Cadman!) found a ready-built one that was a big help.

PerfectIt is not the only add-in you can use. I’ve talked about ClipX before, which is an add-in to Windows rather than Word. It’s a clipboard expander that allows you to see the last 25 entries in your clipboard, so you can reuse them. I’ve just discovered it too has add-ins and one, Stickies, maintains a constant list of entries. I use this a lot when I’m manually tagging a file, so I can quickly insert tags.

6. Learn Word

I’ve saved this for last, but perhaps it should be first. Invest some time in learning to use Word to its full potential, as it will repay you time and again. Many of the things above are rooted in a knowledge of how best to use Word. As you get more familiar with Word you’ll be able to customise your set-up, helping you to use it more efficiently. A great resource to help with this is the CIEP course Editing with Word. This will give you a good introduction to many of the things I’ve talked about above.

Andy Coulson is a reformed engineer and primary teacher, and a Professional Member of CIEP. He is a copyeditor and proofreader specialising In STEM subjects and odd formats like LaTeX.

 

 


‘What’s e-new?’ was a regular column in the SfEP’s magazine for members, Editing Matters. The column has moved onto the blog until its new home on the CIEP website is ready.

Members can browse the Editing Matters back catalogue through the Members’ Area.


Photo credits: keyboard – Halacious; tourist map – pixpoetry, both on Unsplash

Proofread by Emma Easy, Intermediate Member.
Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.

What’s e-new?

By Andy Coulson

At the time of writing this I am in lockdown at home and realising the changes and compromises this means. Thinking back to when I started, technology has evolved so much that it has helped with these challenges in a way I couldn’t have imagined 15 years ago. So, I’ve compiled a list of technology-based or focused resources that I hope will prove of some help.

1. Help! How do I fix my computer?

I suspect this may be something we will all come up against sooner or later. The good news is that there are lots of good resources that can walk you through common problems. Even if your PC or Mac is down you can search on a smartphone and hopefully get yourself running again. Sites like wikihow.com; helpdeskgeek.com; dummies.com; techrepublic.com and Microsoft’s own answers.microsoft.com and support.microsoft.com are all helpful.

A carefully thought-through Google search will often be the best approach. For example, ‘Word 365 normal template’ gives good answers as to why Office 365 keeps flagging the normal.dotm as corrupted. It contains the version of Word and the specific item that is causing the issue. If your computer is giving a fault code or description, include that in the search too.

I’ve written before about backing up, spring cleaning and virus scanners, and all these tips and tools are still relevant. I’ve recently been pointed towards Microsoft’s Safety Scanner, which is an additional, occasional-use virus checker. It is good if you suspect you have a virus, as you can download and run a clean copy of the scanner (if you do have a virus, that may have compromised the scanner on your system).

Finally in this section, Microsoft Word itself is a prime cause of the air turning blue around my workspace. Again, Microsoft’s own support pages can be really good – support.office.com. Our own forums are also a good source of support (forums.ciep.uk), with many experienced word-wranglers being regular contributors. One of my favourite sources of help to answer ‘how to’ issues in Word is wordribbon.tips.net/index.html, and it is well worth subscribing to their newsletter.

2. Managing your time

While I’m at home I find I am facing two opposite problems with managing my time. The first is that it can be difficult to focus and stick at what you are doing. The second is the polar opposite of that: using work as a distraction and spending too long nose to screen. But we can use technology to help in both cases to nudge us in the right direction. I’ve written in the past about approaches based on the Pomodoro technique, which encourages you to keep going for a fixed amount of time, or conversely take a break from work after a fixed period of time. The suggestions here are two examples on that theme.

Forest is an app that tries to help you focus by making a game of focusing on a task. You set the timer for as little as 10 minutes through to 2 hours. Each time you start a stretch of work the app plants a virtual tree. Complete the stretch and you start a forest. Quit and your tree dies. It’s a simple idea and strangely addictive. You could use this either to build up your focus or to remind you to take a break.

Workrave is aimed at helping people recover from RSI, but is also a useful tool to encourage you to take breaks from the keyboard and mouse as you work. It produces gentle reminders, which you can configure, to take frequent microbreaks and longer breaks to step away from the computer, and you can even set a daily maximum.

3. Staying fit

Keeping healthy is one of the key things we are being encouraged to do, and there is a massive number of resources that have been made available in response to the lockdown. YouTube is a particularly good resource, and all the suggestions below can be found there.

Normally I’m a keen swimmer and cyclist, but am not getting very far (yes, pun intended!) with either at the moment. However, the Global Triathlon Network has a number of very accessible workout suggestions, despite the elite-sounding name.

If you have kids at home (or even if you don’t), Joe Wicks’s The Body Coach TV channel has a regular PE-with-Joe session. He also has a range of other home workouts that need little or no equipment and cater for a range of abilities.

Yoga is another home-friendly exercise, and I find it also helps undo the damage done by sitting in front of a computer for long periods. Yoga with Adrienne and Five Parks Yoga both offer a range of sessions, from basic, short beginner sessions through to longer, more advanced sessions. Headspace have also put a series of Move Mode sessions on YouTube, which are not traditional yoga, but more a meditative approach to movement.

Finally, I’ve really got into meditation as a way of having a break from everything. Headspace, Mindspace and Calm all have a range of shorter (10-minute) meditations freely available on YouTube. I am particularly enjoying some of Headspace’s Meditations from the American National Parks where you are encouraged to focus on sounds or colours instead of your breath.

I hope that is helpful to you. Stay safe, and we’ll hopefully get back to some more techie stuff next issue.

Andy Coulson is a reformed engineer and primary teacher, and a Professional Member of CIEP. He is a copyeditor and proofreader specialising In STEM subjects and odd formats like LaTeX.

 

 


‘What’s e-new?’ was a regular column in the SfEP’s magazine for members, Editing Matters. The column has moved onto the blog until its new home on the CIEP website is ready.

Members can browse the Editing Matters back catalogue through the Members’ Area.


Photo credits: Forest – B NW; keyboard Christian Wiediger, both on Unsplash

Proofread by Liz Jones, Advanced Professional Member.
Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.

Why should editors pay any attention to readability metrics?

By Howard Walwyn

Like other things that are not universally loved but keep coming back – general elections and the X Factor – readability metrics don’t seem to be going away.

There are people out there who like general elections and the X Factor. And there are people out there who like readability metrics. But many who don’t.

“I thought that [setting readability targets] … had long since fallen out of fashion. It’s not a reliable tool, and it’s not appropriate in many circumstances.” (CIEP forum contributor, August 2018)

This view is by no means isolated and is very defensible. Far better to write like a human than to be constrained by over-simple metrics, which don’t capture nonsensical meaning and can be outright misleading about how ‘good’ – clear, simple or ‘readable’ – a piece of prose is.

Young shocked boy holding open book

Photo by Ben White on Unsplash

What are readability metrics?

A quick reminder of what the measures are, pretty much in two classes.

Flesch-type: Simple arithmetic measures of two elements: (i) the ratio of words to sentences and (ii) the ratio of syllables to words. In essence, shorter words and sentences translate to better readability scores.

Other: Widely used by Search Engine Optimisation (SEO) tools, a separate but related class of measures looks at frequency: how often something occurs and whether it is above or below a given threshold. For example if the number of sentences with a passive verb exceeds 10% the prose will be marked down on this metric. Similarly, the number of ‘long’ sentences as defined (20 words, since you ask) shouldn’t exceed 25%. And the number of sentences including a so-called ‘transition word’ should exceed 30%.

Why use readability metrics?

Why would any editor in their right mind pay attention to such simplistic notions?

Well, for two main reasons.

As a benchmark

In their own limited way – not sufficient, not even necessary, but still useful – these metrics support intuition surprisingly well. A postgraduate thesis will score around 30 on the Flesch Reading Ease measure. This is one version of the simple ratios mentioned above, scaled into an index which can be then attributed to different reading levels. 30 is hard to read. 60 is plain English. 100 is readable by an eight-year-old child.

I think of them as no more than benchmarks: background data in the back of my mind which helps me judge (1) the level of reader who find might this piece easily readable – which may be very different to who it is aimed at; and (2) how a piece compares before and after editing or compares to work by a similar but different author.

I emphasise that I fully understand the technical limitations. I wouldn’t judge a piece based solely on the metrics. But I do find the information they give me is valuable in its own terms as part of my assessment of the piece.

You can’t drive a car based solely on the speedo. You don’t even really need it that much if you’re an experienced driver. But it’s still a useful part of your armoury at the wheel.

Because clients do

This is perhaps the main reason in practice we, as editors, should be paying more attention even if we have to hold our noses while doing so.

Increasingly – perhaps reflecting the more general drive towards plain English standards in corporate and official life – non-publishing clients are using Flesch and other metrics explicitly as in-house writing targets. A couple of examples came up in a members’ forum thread on this topic.

“I do some work for a government department … their reports must have readability scores of between 40 and 60, varying according to their intended recipients.” (CIEP forum contributor, August 2018)

I can vouch for this. One of my clients in the finance sector has set external and internal Flesch readability targets for its comms department and its policy gurus respectively. The arguments are as follows:

  1. On the external (comms) side, they want to communicate in plain English and a Flesch measure is an objective way of at least encouraging that.
  2. On the internal (policy) side they want to improve their management decision-making, and clearer internal writing – which they think is at least partially evidenced by a ‘good’ Flesch score – is part of that determination.

We can help

On this basis it is pragmatic and sensible for us, as editors, to develop some expertise in the tools; while not losing any scepticism we may have for them. We can add value for clients by helping them understand the metrics better, and work with them to help them appreciate the limitations. As Luke Finley said on the forum thread I mentioned:

“There’s some evidence applying readability formulas too rigidly can make a text harder to read. To me this is an argument for putting them in the hands of language experts like editors if they’re to be used in a nuanced way.” (August 2018)

In short, keep an open mind. It could help you in your business if you have this expertise. I wouldn’t necessarily suggest volunteering them if the client doesn’t use them. But even that may be apt and valuable for certain types of non-publishing client. And you may help mitigate some of the misapplications that come with limited understanding.

You can even have fun with them. I expose my students’ work to the measures and they are often thrilled or horrified to see how academic (read tortuous) their business writing has become. And often pleased to be set on a path which involves a clear metric (even if a limited one).

Want to know more?

For more information I have published two (yes, two!) blogs on this topic, which I suppose reveals my interest: Flesh of my Flesch and The Pix Simplicity Measure.

And for a bit of further informative fun, here are the readability metrics for this blog:

  • Flesch Reading Ease 60 (plain English).
  • 24% of sentences are long; 12% are passive; within or close to the guidelines.
  • 34% of sentences with transition words: above the guideline.

In short, I am happy to release this post to the editor in the knowledge that it should be broadly ‘readable’, but you can be the human judge of that!

Howard WalwynHoward Walwyn is a writer, editor, trainer and CIEP Professional Member. After a career in the City, he now helps clients write clear business English and bridge the worlds of language and finance. He is a visiting lecturer in Writing for Business at City, University of London and has degrees in English Language & Literature and Economics. Follow him on LinkedIn or Twitter.

Posted by Abi Saffrey, CIEP blog coordinator.

The views expressed here do not necessarily reflect those of the CIEP.

How to customise PerfectIt to check your house style

By Daniel Heuman

PerfectItBuilding customised style sheets in PerfectIt helps make sure that all documents you work on reflect your or your client’s preferences for spelling, hyphenation, capitalisation, italics, and other house style choices. There are two ways to build preferences into a PerfectIt style sheet. You can either:

  • Commission Intelligent Editing to prepare the style sheet for you. For government departments, NGOs, and Fortune 500 companies, this is the best way to develop the most comprehensive style sheet possible.
  • Prepare the style sheet yourself. For freelancers and small companies, this lets you put together your own style sheet that is customised to your needs without any additional cost.

To have a style sheet prepared for you, you can get a quote from Intelligent Editing. This article is for people who want to prepare their own style sheet. It guides you through ten short videos that, in less than one hour, will teach you how to prepare your style sheet.

Do I need to customise PerfectIt?

PerfectIt doesn’t need any kind of customisation. You can use it to check consistency without altering any settings. Just run it, click ‘Start’, and the interface guides you through the rest. Most people find that’s all they need, without any customisation. If you haven’t ever used PerfectIt, start with the free trial, which you can download here.

PerfectIt also comes with a number of built-in styles, including European Union, Australian Government, World Health Organization, and United Nations styles. If you’re using those (or if you just want to check UK, US, Canadian, or Australian spelling), you can use the built-in styles without any customisation. Just select the style that you want before you press ‘Start’. You only need to customise PerfectIt if you want it to check your specific house style.

Creating a new style

If you’ve decided that you do want to customise PerfectIt and are ready to learn more, the first thing to do is to add a new style. This video explains how:

You can have one style sheet for every style manual (or client) that you work with. So repeat those steps for every style sheet that you want to create.

Customising settings

When you’ve created a new style sheet, you can edit it in PerfectIt’s style sheet editor. This video looks at the ‘Settings’ tab and shows how to check your preferences for lists, compounds, and headings. For example, you can set PerfectIt to enforce punctuation at the end of a bulleted list or to control title case in headings:

The next video shows how to use the settings for numbers in sentences and Oxford (serial) commas. You can turn Oxford commas off or on, and you can choose whether numbers in sentences should be spelled out or presented in numerals. In addition, it shows how to set a number of style points such as thousand separators and non-breaking spaces in measurements and dates:

Search and replace

You can modify PerfectIt’s tests by adding particular words that PerfectIt should find. In addition, you can choose words or phrases that PerfectIt should suggest as fixes. To see this, go to the ‘Always Find’ tab in PerfectIt’s style sheet editor. Each test within that tab is a little different. This video shows how to add searches to the tests of hyphenation, dashes, accents, and phrases in capitals:

The next video looks at PerfectIt’s different tests of spelling as well as the test of phrases to consider:

The final video on the ‘Always Find’ tab covers the test of comments that are accidentally left in the text and the test of abbreviations that appear in two forms. Then there is a more advanced tip on adding exceptions:

Additional tests

PerfectIt’s style sheet editor has tabs for PerfectIt’s tests of italics, prefixes, and superscripts and subscripts. This video covers all three, and shows how, in addition to switching the settings, you can add additional words/phrases to each test:

If you’re not familiar with wildcard searches in Word, it’s worth reading up on those before watching the next video. Two great sources to look at are Jack Lyon’s Advanced Find and Replace for Microsoft Word (an especially good resource for beginners) and Graham Mayor’s article on Finding and Replacing Characters Using Wildcards (a useful reminder for users who are already familiar with the concepts of wildcard search).

For those who are comfortable with wildcards, this video shows how you can include them in a PerfectIt style sheet:

An even easier way

The videos above explain all of the features in PerfectIt’s style sheet editor. However, if you’re concerned about the time involved in entering all the preferences in your style manual, there is a way to complete the task gradually. And it’s really easy. This video shows how you can amend a style sheet as you work without ever opening up PerfectIt’s style sheet editor:

Sharing styles

The great thing about style sheets is that it only takes one person to prepare them. After that, you can share the style with anyone at your organisation. This video shows how to share your style:

Slow and steady…

If you have spare time to set aside to prepare a style sheet, that’s fantastic. But that’s a luxury that many people don’t have. So what we recommend is to start with an existing style and amend that (as shown in the first video above). Then go through and complete the preferences in the ‘Settings’ tab (the second and third videos). Then stop and just do a few minutes per day after that. Adding to styles incrementally as you work is easy (the ninth video). And if you add just two or three items to a style sheet with each document you check, then you’ll quickly have a style sheet that saves time and improves checking for everyone at your organisation. And it doesn’t cost a penny extra!

Daniel HeumanDaniel Heuman is the Founder and CEO of Intelligent Editing as well as the developer of PerfectIt.

 

The views expressed here do not necessarily reflect those of the SfEP.

Writing out web addresses

Here’s a question I’ve seen a few times of late: when writing out a web address, must we include the whole address or is it safe to omit part of it?

Some house styles set out guidelines for writing web addresses. One would think, then, that the practice is simply a matter of style. In fact, it mostly is – but not always.

So that we know the names of the components that make up a web address, let’s take a look at an annotated example:

Components of a web address

Keeping with protocol

Web addresses begin with a ‘protocol’, the most common being http:// and https://.

From the technical point of view, the protocol isn’t usually required when quoting web addresses. To use the SfEP’s own website as an example, all modern browsers will treat the following addresses as equivalent:

When it comes to being consistent, we wouldn’t usually want both styles of web address to appear in the same piece of work.

The complications tend to come about when we start introducing addresses with other protocols to the same document. For example, if we wanted to make specific reference to a secure website, it would be correct to indicate this by including the protocol in the address, such as:

The intelligent reader will see the protocol and immediately understand that the website is secure, regardless of any other information about the site in the text.

Almost every website that has a secure area will also have rules that discreetly redirect users from the standard protocol (http://) to the secure protocol (https://). To demonstrate this, one can visit the following address:

Now, because a protocol hasn’t been included in the example above, the browser will try to take the user to the http:// version of the site (this is the default behaviour of all web browsers). Seeing that action, the server running the website will automatically and immediately redirect the user to the https:// version.

In short, this means that, even for secure websites, a protocol isn’t usually required in the address. I write ‘usually’ because there are some rare cases where web servers may display the wrong page if the secure protocol is not specified.

In cases where any protocols are included so as to give the reader a cue, it stands to reason that all other web addresses in the same document should also include protocols, on grounds of consistency.

In a document where standard web addresses are the only ones used (i.e., http:// and nothing else), it seems unnecessary to include the protocol. Omitting the protocol is both consistent and technically correct.

Handling new domain names

One common reservation with omitting protocols is when it comes to the newer domain suffixes, many of which most readers may not have heard of. Here are some examples:

If you saw these in running text, would you know that they were web addresses? Or might you think they were the ends and beginnings of unspaced sentences? The caveat here is that if unusual or novel addresses are used in a document, they might be worth qualifying with a protocol – and in turn that would require every other address in the document to include a protocol, too (on the assumption that we’re going to be rigid about consistency).

The cautious editor could use this argument to recommend that protocols be included on all addresses, to prevent a major rekeying effort in the event that some novel address is later added to a work that had previously contained only run-of-the-mill addresses. You’d have to make a decision about whether this would be too cautious an approach. For what it’s worth, I’ve been omitting protocols for quite a while now, having previously been a staunch supporter of mandatory inclusion.

Omitting the ‘www.’ part of an address

Some people don’t know that it’s usually possible to omit the ‘www.’ part of a web address and still be able to retrieve the website. This part of the web address is known as the ‘subdomain’. Most web servers are set up so that the domain (the key part of the address) and the ‘www.’ subdomain each allow access to the website. Here is an example:

Unfortunately, it’s not always possible to omit what would otherwise be a redundant ‘www.’ from the address. Here are some examples:

Trailing slashes

A trailing slash is the forward slash character (/) sometimes added to the end of a web address. This should be added only to the end of a domain name or a folder name in the address. Here are some examples:

  • www.example.com/ – correct
  • www.example.com/folder/ – correct
  • www.example.com/folder/file.html/ – incorrect

One might wonder why a trailing slash would ever be added to a web address, given that the website ought to be displayed just as well without it. The answer is that the appropriate use of the trailing slash eliminates one unnecessary request from your computer to the server, thereby reducing the load on the server. You might not notice any positive effect, but it’s still a good practice to adopt: very busy servers will run better if their load is lightened in any way.

Web addresses followed by punctuation

A web address directly followed by any punctuation mark has the potential to confuse, because some readers may incorrectly interpret the punctuation mark as being part of the address. Word processors and email programs can sometimes be guilty of this mistake, turning an otherwise correct address into a link that doesn’t work when clicked. Thankfully, this is less of an issue than it once was.

It’s quite easy to fall foul of the ‘address plus punctuation’ problem when copying and pasting an address. It’s therefore sensible to avoid directly following an address with a punctuation mark; however, if the context is clear or the readership is web savvy, there may be no need to reword the text.

In my opinion, the omission of a terminal punctuation mark for the sake of clarity is preferable to the occasional practice of adding a space between the address and the punctuation mark. As usual, we should be consistent in the handling of all such matters.

Conclusion

If your client’s style guide sets out preferences for how to write web addresses, you should of course follow those preferences. But be mindful of any newer types of address that might confuse readers, and check that all addresses do indeed work as written.

If you have no style guide from which to work, remember that it’s perfectly fine to use the shortest possible address that will result in the desired website being loaded correctly.

John EspirianJohn Espirian (@espirian) is the SfEP’s internet director and principal forum administrator.

As a freelance technical writer, John specialises in producing online help content that’s actually helpful.

 

Proofread by SfEP Advanced Professional Member Etty Payne.

The views expressed here do not necessarily reflect those of the SfEP.