Category: Technical Writing

About Technical Writing

Subscribe Feeds

Reaching out

Posted on by Ducky

On the 10 July 2013, I gave a presentation at Edinburgh Tech Meetup on documentation. The audience was a room full of software engineers – some were freelance, some were managers of small startups, some were students who hadn’t entered industry yet. The video and slides are available on my presentations page. After my presentation, I was contacted by the editor for Communicator, the journal for the Institute of Scientific and Technical Communicators (ISTC), and asked if I would write an article on the topic.

I wrote the following article for the Winter 2013 edition of Communicator.

Reaching out

Not everyone likes writing documentation. Denise Marshall explains to developers how to stop worrying and love the document.

In my experience, it is the rare software developer who enjoys writing documentation. I have become accustomed to looks of bafflement from software developer friends. Their experience is the polar opposite of my own: they find it profoundly frustrating.

One of the regular events that I attend is Edinburgh Tech Meetup. It’s primarily a networking event for freelance software engineers, software startup founders, and many others who are generally interested in computing. One evening every month, the group meets to listen to two presentations and spend several hours in discussion. While I usually find the talks interesting, my primary interest is meeting with other members in the software and technology community. It was in a conversation with a developer at one of these evenings that I realised that documentation is getting a bad name among those who could be its staunchest allies.

“What can I say to my boss to convince him to hire a technical communicator?”

As I conversed with the developer, I heard a story that I’d realised I’d heard several times from different software engineers. There seems to be a level of wishful thinking present in the software world that says that the software product should be obvious enough to the users that documentation simply isn’t necessary. Likewise, the code should be obvious enough to anyone who’s reading the source code that a couple of comments in the source is sufficient to understand how all the sources work together. Of course, most developers are aware that this is a pipe dream.

In reality, documentation needs to be available alongside the product. For the work that I do, my readers often don’t refer to the documentation except in their hour of need, either when the workflow isn’t obvious and they cannot find the solution themselves or when they want confirmation that what they’re about to do is correct. For my documentation to be useful, it needs to be thorough enough that they can find the answer to their question and clear enough that they can understand the solution.

The organisations that these developers work for rely on them to document their work. This makes sense because the developers know what the software is meant to do (they have their formal requirements, at least) and they know how to use it. It follows, then, that it would take the developers little time to write up what they’ve done, because they’re the ones in the best position to know what they’ve done.

But these same developers have deadlines that they must meet to deliver the software and are often too pressed to make time for documentation. With documentation included in the requirement, the organisation’s projects can fall behind. The inevitable cycle would lead to someone in management deciding to hire another developer to take up the slack. The existing developers don’t know how to write documentation and get frustrated that more and more of their time is wasted (their words) on documenting their code, rather than being spent on writing good code. Sadly, the blame is placed on the documentation for putting them behind schedule. To add to the feeling of frustration, the developers I speak to generally feel that they weren’t documenting well, because they didn’t know what they were doing. And the new developer needed to be brought up-to-speed, further slowing the development process. I offered the best advice I could: “Convince your manager to hire a technical communicator. They’d happily do the documentation part of the process.” Then would come the inevitable reply: “My manager says we can’t afford a technical communicator. Could you give me some pointers on how to get started?”

What could help their experience with documentation?

I set about creating a primer on producing documentation for those developers at Edinburgh TechMeetup who had no choice but to provide the documentation because their companies could not take on a technical communicator. I could, at the same time, provide those employers who had never considered hiring a technical communicator with an argument for considering one in the future. I knew that the audience I would have in front of me would see documentation as something unpleasant so I wanted them to know that I knew where they were coming from.

A primer on documentation

I’m fairly certain that any reader of Communicator will know how best to communicate information to their audience – it probably comes as second nature – but, for the uninitiated, it can be a baffling world of text editors, words, and images. I laid down the basics that a non-technical communicator would need to produce a minimum standard of documentation:

  1. Know your audience. If you know who your audience is, then the style and content of your documentation often becomes obvious. For example, if you are explaining to a developer how to use the different functions of an API, then an API reference guide makes sense. If you want to get new hires up to speed quickly then a wiki with some overview information might be sufficient. Do you need to explain how to use software to groups of pre-literate children? Pictures might be best.
  2. Create a structure. This can sometimes be hard but I find that, in the absence of a strict template, it’s often made easier by writing each idea into separate topics on notecards. These notecards can then be grouped, arranged, and rearranged until they make the most logical sense. This also encourages topic-based documentation. (I also reassured them that, after they’ve got a basic outline, they can save it as a template to simply fill in the next time they needed it.)
  3. Find your style. Be Consistent and Be Clear. For example, there are many ways to write ‘email’ (Email, E-mail, email, e-mail, eMail, etc), but as long as you pick one and stick to it, you’ll never have to wonder again which is the correct one. Likewise, phrases such as ‘Enter text into the text field’ should be made consistent (other options might include ‘Type text in the field’, ‘Write text in the box’, and ‘Fill in the text’). If you write the phrases consistently, the perceived quality of the documentation increases and the technical communicator can move more confidently into other areas of the writing.It’s also important to avoid ambiguous language. While it can sometimes be hard to know if your sentences will be misread (that’s where asking someone else to review it is useful), it’s easy to avoid ambiguous words. A list of words that should be avoided can be added to a personal dictionary in your preferred word processor. At the top of my current list are ‘since’ (when you can use ‘because’), ‘once’ (when you can use ‘after’), and ‘appears’ (instead, use ‘opens’ or ‘is displayed’).
  4. Consider graphics. Graphics should be avoided unless you’re absolutely sure that you need them. This reduces file sizes, reduces translation costs, and means that you don’t need to update them with every small UI change. There are times when graphics are good, such as when you’re drawing a diagram of system architecture and it’s important to consider your audience when deciding the necessity of graphics – some audiences might genuinely require a screenshot of every single page in a Wizard.

And that was it. I tried to keep the rules as simple as possible, in the hope that some of it would stick. If one developer could, at the end, decide who their audience was, organise their ideas, and be consistent throughout, then I knew it was worth it. But I wasn’t quite done yet.

Is it worth hiring a technical communicator?

After explaining to an entire room of developers how to approach technical documentation, I asked them the question that was at the heart of the reason that I delivered the presentation: “Would you rather be writing documentation than coding?” The only people in the room who raised their hands were, like me, technical communicators. Every developer I’ve ever worked with has expressed how much easier we make their lives, because we know how to put all the things they know into words on paper. Unfortunately, many in the audience hadn’t had the opportunity to work with a technical communicator. So I laid it out as succinctly as I could:

Hire a technical communicator and the developers have more time to code. Yes, they still spend time on documentation because they need to explain things to the technical communicator, but it is a very small fraction of time compared to what they would be spending otherwise. In addition to that, the technical communicator would be more efficient because they would know how to write.

Reaching out

The most surprising thing that happened, at the end of the talk, was that a developer approached me and confessed that he didn’t think he was going to like my talk. He’d done documentation before and, like the others I’d spoken to, didn’t like it and didn’t really see much use for it. He told me that he was inspired to start documenting the project he was working on. Another developer told me that he’d never heard of technical communicators and had a friend who would probably love the job and asked if there were any training courses available.

I hope this article has helped you realise that we don’t need to limit our audience to the readers of our documentation.

The Techaddicted Guide to Documentation

Posted on by Ducky

I’m forever telling my developer friends that “Documentation is not a dirty word!”. But, for most of them, documentation is that thing their managers tell them they need to do, that thing that gets in the way of coding, that thing that takes forever because they don’t know how to do it and the don’t want to do it. These same friends keep asking me “We’re falling behind schedule at work and so my boss wants to hire another developer — I suggested hiring a writer but apparently we don’t have the budget for that! How do I convince management that it’s worthwhile to hire a writer?!” I’ve previously written a blog post about this, but I realise it’s not enough.

So I put together a presentation that addresses two main points:

  1. How to write documentation – Because sometimes documentation is inescapable and it doesn’t need to always be painful.
  2. How to justify hiring a technical writer – Lacking hard statistics, but with a story and diagram.

I presented this at Tech Meetup Edinburgh back in July. You can watch my presentation below (30min, including questions) or you can just flick through the slides yourself (View Slides).

Denise Marshall talks about Documentation from TechMeetup on Vimeo.

NOTE: Most of my images are from XKCD. See http://xkcd.com/license.html for license info.

Words to Avoid

After my presentation, I got a few requests to share my list of Words-to-Avoid

That list can really be broken down into two categories:

  1. Ambiguous words – they have more than one meaning and both meanings are frequently used. But one way of using the word can be easily replaced with another, non-ambiguous word. Sometimes you need to use a word that has multiple meanings, but if you consistently use it to only ever mean one thing, then that goes a long way to helping keep things clear.
  2. Warning words – words that should warn you that your writing is in the wrong tense, wrong tone, or something else un-good.#

Lets start with the ambiguous words….

Ambiguous Words

Once

Once should only ever be used to mean one time. You do something only once. Though once upon a time doesn’t really belong in serious documentation. Most of the time, the word after is a perfect drop-in replacement for the incorrect usage of once.

Hint: If you use once at the start of the sentence, it’s probably incorrect. Sometimes it’ll be in the middle of the sentence. Every time you use the word once, think to yourself if you can replace once with after and keep the meaning of the sentence – if you can, then do it.

Good: Click the button once to save your document.
Bad: Once you’ve clicked the button,  the system restarts.

Replace bad of once with after

Correction: After you’ve clicked the button, the system restarts.

Since

Since is commonly used in conversational English to mean because. For example, “Since I don’t like peppers, I always have to pick them off of the veggie pizza” is fine for explaining that I am picking peppers off my pizza because I don’t like them. But since also serves as a great word for describing “time that has elapsed between this previous event and now” quite succinctly, such as in “I haven’t eaten since breakfast”. Because since can easily be replaced by because in some cases, the because sense of since should be replaced with because to make the usage of since in the temporal as unambiguous as possible.

Good: If you have not restarted your system since installing updates, do so now.
Bad: The updates have not been fully installed since you have not yet restarted your computer.

Replace bad since with because

Correction: The updates have not been fully installed because you have not yet restarted your computer.

May/Might

May and might suffer from the same problem — are you trying to say that it is possible that something has the ability to happen or are you saying that something has permission to do something. It’s like being back in school again and Miss is telling you “Yes, you can go to the toilet but no, you may not”.

Just forget about may and might and your Miss who’s making you hold it until lunchtime. Just use can and could instead. But when would you use which?

  • can for permission
  • could for ability

Good: You can create a new customer account.
Good: The system could crash if you do not create the order using the wizard.
Bad: You may create a new customer account. (Do you mean “You have permission to”? “You have the ability to”? “There is a possibility that you want to”? etc. So many different meanings!)
Bad: The system might crash if you do not create the order using the wizard.

Warning Words

Will

If you’re using the word will, it means you’ve slipped into future tense. Stay in present tense.

Good: The report opens.
Bad: The report will open.

Please

You don’t need to be nice in serious documentation.  Conversational writing can work for you, but be careful of humour in technical documents. Humour is difficult to read and is even more difficult to translate. If you’re including words like please, you may be slipping into other casual language. In technical documents, just stick to the facts.

Please implies that the reader does not need to do what you’re going to ask them to do and that you don’t think they’ll like to do it – you just need to tell them do do it.

Should

Nothing should happen. Either it can happen or it does happen.

“DOs and DON’Ts” or “Do’s and Don’ts”?

Posted on by Ducky

I was minding my business on the internet when I happened upon a review of the new Microsoft Manual of Style for Technical Publications on Kai Weber’s Tech Writing Blog. It was an interesting review (you should go read it) so I thought I’d have a look at what the going price is for the new Manual of Style.  A Google search for Microsoft Manual of Style took me to the Microsoft webpage on the third edition where I saw a bit of text that had my inner-editor shouting “NO NO NO!”.

Use technical terms correctly and consistently—including do’s, don’ts, and alternatives for usage.

When I was first taught about the apostrophe, the rules were simple:

  1. An apostrophe signifies a contraction
    Example: “I cannot” contracted to “I can’t”
  2. An apostrophe signifies possession
    “Alice’s new shoes”

But as I got further in schooling, there seemed to be this grey-zone of plurals which seemed better with apostrophes. Wikipedia mentions some such as when pluralising lower-case letters:

Be sure to dot your i’s and cross your t’s

It’s certainly not the “grocers’ apostrophe” that raises the hackles of copyrighters everywhere (Apple’s £1.50/lb). Surely nouns shouldn’t ever require an apostrophe to be pluralised… But what about those grey-zone ones?

Is the phrase do’s and don’ts correct in its punctuation?

It seems to me that it’s the pluralisation of do that seems to visually require the apostrophe. Without it, it risks being mis-read as a mis-spelling of does, or perhaps (Microsoft) DOS.

I, personally, would use DOs and DON’Ts, relying on the difference in capitalisation to make it easily readable. But which is right? I struggle to think of any other phrase that requires the pluralisation of do, this shortened phrase that means “A list of things to do and a list of things to not do”. Using the capitalisation also invokes the image of two side-by-side lists, topped by the words DO and DON’T. But does anyone agree with me?

I did another quick Google search for Do’s vs DOs to see what what the forums of English pedants might suggest. Here’s a quick summary of  the first few  Google hits:

Site Do’s Dos DOs
EnglishForums.com Y N No mention
Answers.com Y Y No mention
BeeDictionary.com Y Y No mention
DemocraticUnderground.com Y Y No mention

To be honest, a lot of the forums in the first page of hits seemed more concerned by the Don’ts, assuming that there SHOULD be an apostrophe in do’s so should it be written don’t’s. And no one seems to care about my solution of DOs.

Conclusion: These days, it seems like you can do whichever makes you happiest with this particular phrase. Oh, well. It’s a good thing I don’t use the phrase in documentation.

“Sounds like you need a writer.”

Posted on by Ducky

Most companies value documentation. I keep talking to software developers who’re working for small companies and they all say “yeah, our boss knows that its important to have documentation, that’s why he has us document as we code…”

It’s great that they know that having documentation increases the customers trust in the product or service. Unfortunately, there’s a “but”.

“But,” my friends tell me “I hate writing the documentation. And I always have to spend so much time figuring out how to write things. I know how to write code, but I’m not sure someone else would understand my documentation…”

Yes, a technical writer takes some time away from the developers, as they need to describe what a product is and how it’s meant to work. But we save time in the long run because we can just get on with the writing — and in the end, we tend to produce much higher quality content and a much better document than your stereotypical software developer.

If the developers at a company are spending a large chunk of their time writing documentation rather than coding, and there’s more work than people, then it may be worth looking into hiring a technical author instead of another developer. The developers you already have can spend more time writing the code they were hired to write and the technical writer can pick up and improve the documentation.

The quality of documentation your company produces is just as important as the quality of the software you write or the service you provide. If you give customers poor documentation, it could affect their opinion of your overall company image.

For more information, refer to the Institute of Scientific and Technical Communicator’s page on Why Use a Professional Communicator?.

Open Source Orientation

Posted on by Ducky

How many of you have heard this before:

“I had a look at [product] but I couldn’t quite figure out how it works. There was a community message board, but no real documentation.”

Welcome to the world of open source software, where there is a sad lack of documentation. I know, I’m not really in a position to complain, being one of the people in the community who could write some documentation for community project but hasn’t really. Well, except for this one time…

Picture it – the year is 2010 and I am on the cusp of graduating from university, with a degree in Linguistics and only a year of technical writing experience. I’ve spent the last two years evangelising about the wonder that is the open source community and I want to jump in and do all I can to help. So I went along to the Open Source Jump Start 2010 in London. I’m in a room with 30 other university idealists who want to help something bigger then themselves. There are project leaders from many different open source projects – and they take us by the hand and introduce us to their projects.

That’s the hardest thing, getting started. With no documentation, and no one to explain what this particular program is meant to do, I’m lost. I can read code, but it takes me awhile – like someone with a knowledge of Spanish attempting to puzzle through Portugese. It really does take either a fair amount of discussion on a message board, or a sit-down with one of the developers to really understand how something works.

That was the beauty of the Open Source Jumpstart – the would-be programmers had a chance to discuss the project and its organisation. I, too, had the opportunity to talk to the project leader of the Citrine Scheduler project and write a bit of documentation.

I want to organise something like that in Edinburgh, where I know there are people who would want to get involved, students who need to work on open source projects for their degree and folks who’d love to help out the community but don’t know where to start. That’s what I had said on the day I was there, something I have talked about on-and-off ever since. Now that I’m back in Scotland, I don’t have an excuse anymore.

It’s more than just documentation — documentation helps get your foot in the door, but talking over pizza also helps get your foot in the door.

Anyone else want in?

Writing Tools

Posted on by Ducky

One of my fellow technical writers asked me a question that should have been easy enough to answer:

“After spending the last year using FrameMaker 8, what would you want to use if you started at a new company that didn’t have any existing documentation? Would you want to go back to LaTeX or would you ask them to pay for you to get FrameMaker?”

I was first of all amused that she didn’t assume that I would go for RoboHelp, one of the other documentation programs we use. There was also the assumption that I wouldn’t want to try something I’ve never tried before.

Then I had a think about it.

  • Am I a lone writer because they have very little documentation that needs to be created or am I the first of what will eventually be a team of many?
  • Is the documentation going to be online help, CHM, PDF?
  • How much money does the company have to spend on documentation, after paying me?
  • Does the documentation need to be released as soon as possible or is the software in the early stages of development, giving me time to develop the doc set?

All of these thoughts come together to decide how I would approach new documentation.

I know there are other tools available that I wouldn’t use for customer-facing documents, such as wikis (because of how difficult it is to keep them structured and ensure that all your pages are up-to-date) and plain text files (acceptable for short READMEs, but messy for long documents). There are also long lists of tools that I’ve never used before so don’t know the value of, such as Flare, DITA, and Author-It.

My first technical writing job, I worked for a very small company. I wrote everything in LaTeX, due to the ability to make a nice template, the ease of adding content, and the openness of the software to edit it. Free software to create the doc, ability to output as PDF and HTML. Everyone’s happy, right? Except most people don’t want to have to edit LaTeX because it can sometimes be fiddly and software developers have better things to do than chase an orphaned sentence.

If I were to go back and do it again, knowing what I know now, I would probably do the documentation in Microsoft Word, but with a fixed template. The developers left updating the documentation in my absence would be happy, and marketing could more easily copy text from the documents. Even the cost of the Microsoft Word license is effectively zero since everyone had it anyway. And in the end, I never did need the HTML help.

If I worked for a very small company that needed primarily HTML help and the occasional PDF, I would probably use Adobe RoboHelp. Compared to other documentation software, the license is cheap, I already know how to use it, I can create templates for it, and (as long as I’m very strict about how a project is organised) it can produce good HTML help as well as PDFs.

I’ve mostly enjoyed FrameMaker 8, this last year. Our template is solid and we’ve got a strict style guide, so our documentation is consistent across writers and product suites. I mostly like the user interface and I know that more recent versions have fixed those few things that really rub me the wrong way. It even has the very useful features of conditional text and text insets. But, it’s expensive. It gets even more expensive if you want it to create HTML or CHM, since you need WebWorks ePublisher.

If the company were intent on expanding, both in terms of software suites and staff writers, I’d push for FrameMaker. At that point, they can probably afford the licenses for it, and it gives a much more structured doc set.

If the expanding company also had time to let me research and try different things first, I’d really want to give Structured FrameMaker a try. The idea of XML organisation in documentation makes me pleased as punch and, from what I’ve read about it, sounds like the sort of thing I’d really like to use.

This is one of the things I like about working with different people on different projects – I get to learn about all sorts of new tools. Maybe my next job will need me to learn DITA.

Language Log Name Check

Posted on by Ducky

When I walked into the office kitchen yesterday, I overheard some of my software developer comrades discussing Language Log. As I made my way to the coffee machine, one of them asked me “Hey, are you the one mentioned in that Language Log post about ‘Every Little Helps’?”

Completely caught off-guard, I sputtered “uhm, yeah.”, thinking back to the day that I brought the topic up with a lecturer after class, and he posted about it on Language Log to find out what it was all about.

“I KNEW it!” he exclaimed in response. “Though I’m sure there are only so many American undergrads named Denise Wood studying Linguistics in the UK… Cool!” I couldn’t help but wonder to myself if this is the single greatest moment for me in the field of Linguistics, a name-check on Language Log. Instead of an Erdös number, I’ve got a Language Log number of 2 — Though I’ve never posted (not even replied), I was written about by a poster on language Log.

The discussion around the coffee machine then went on to discussing syntax, until another programmer walked into the kitchen and we realised we’d been standing there far too long and rushed back to our desks.

I’m OK with the fact that I’m not really pursuing a career in academia, where I can say “I am a Linguist” when people ask what I do for a living. I’m a technical writer, I work with software programmers. I still get to spend all day thinking about language and how we use it, though. I also get to have these beautiful moments when I realise that the polymath is not a thing of the past — my programmer friends read my favourite blog and can discuss linguistics with as much comfort as they discuss maths, chemistry, and code.