Hot answers tagged

45

A few additional options: Introduce a named person (perhaps fictional), and use that person's name. "Terry wants to create an account. She chooses a password and types it into the text box. No, wait, Terry is a man. I think. Damn, that's a lousy example. Pat wants to create an account. Um, I mean Chris. No, wait. Maybe Dale. Er..." Use the imperative mood, ...


39

Close the intro. Promise yourself that you will write it last. Start a blank Scrivener page. Start writing down everything that comes into your head about the topic. Follow your thoughts wherever they lead, but make each thought a new line. Don't organize; just write. When you run out of steam, go back to the top of the list, look at each thought, and ...


31

I really like this question. I cringe to say it, but I somewhat agree about breaking grammar rules in the interest of safety. I frequently write technical emails/IT system announcements that are sent out to a large group of non-technical people and I find that if I write the emails using the same language that I'd write in my short stories, or even my ...


22

Am I allowed to beat the drum for Scrivener again? :) Scrivener is a tremendously flexible writing program which allows you to rearrange your items easily, by dragging around icons, by putting up virtual cards on a corkboard, or setting things up in outline format (the Outline view is right in the top bar). Each item of your outline is a document, which ...


21

No, users are not stupid, it's usually the designers that are. A good UI requires a solid understanding of HCI (Human Computer Interaction) concepts, which range from understanding the target audience, to cognitive load theory. You might be able to get away with "idiot proof", since it's a cliché. Personally I'd avoid painting the users with a broad brush, ...


20

A non-technical test reader would be a helpful resource. Because of your knowledge you are blind for so many details, which you take for granted and couldn't believe that other do not know them. Listen to a test reader, what he does not understand, is the way to identify these blind spots. The problem with this approach: you need regularly new test readers, ...


19

Of course you can't just ignore all basic grammar rules. For example, writing: Not cover the opening machines power be while do. obviously makes no sense to anyone, even though it's got all the right words (plus or minus a few grammatical suffixes) in there. It's just broken English. But you can totally write, say: Do not open cover while ...


18

Shall is still used in software documentation. It was a subject of discussion in my software engineering course and it's also present in field documentation. An example can be found in the Joint Strike Fighter's C++ coding standard. In section 4.2 under Rules on page 11. It specifically defines the following: 4.2.1 Should, Will, and Shall Rules ...


17

The number one thing that you have to realize about technical writing is that people do not read it for its own sake. They read it because they are trying to do something and they need more information. The writing does not need to engage or entertain because the reader is already engaged with the task. It is their engagement with the task and their need for ...


17

The label should be as short as possible without creating ambiguity. In many workplaces, the employer is required (OSHA, ISO, FDA, etc.) to train anyone who would be working in a particular area with the hazards of the environment and the equipment. The label acts as a reminder (as well as a legal obligation). Everyone in that lab knows lighting a flame ...


16

Short answer: Yes. Slightly longer answer: Yes, a lot! All reading is good, but not all reading is equal. All reading will help you absorb the effective use of written language, will increase your facility with words, will enhance your vocabulary, etc. But if you're really serious, you should spend at least some of your time in conscious, directed ...


16

That depends entirely on a number of factors: What's your motivation? (Thanks, Steven Burnap for this one.) Do you just want to get it out there to share your knowledge? Or are you looking to make money (hint - you probably won't make much money off your first book, no matter what route you go)? Dead tree? Ebook? Both? Something else? This is going to ...


15

Very few use he/she. In academia, there is currently a movement toward using the feminine pronoun at all times. That said, it is far more common (and less remarkable) to alternate pronouns as you suggested. As long as you stick with the same pronoun per example you'll be technically correct, although it is increasingly un-PC to use only male pronouns. Until ...


15

You cite a source because it gives additional information that a curious reader may want to follow up on. So: If your prior paper gives additional information (data, methods, background, conclusions, further citations, etc.) that is not in your current paper, but which may be of interest to readers, cite it. By the way, you're not citing yourself; you're ...


14

They/their can be used in a singular context The user chooses a password, and then they type the password in to the text box


14

RFC 2119 defines the meanings of various words used in specifications (such as other RFCs). It defines SHALL as a synonym of MUST. I think it's preferable to use MUST, as it conveys the meaning more clearly.


13

I do not know, why it should be dead. Writing and updating several sources with the same content is tedious, error-prone and will cost a lot of money. The idea is to separate content and design. You write the content one time and you generate with different designs/formats websites, PDFs, books, eBooks, whatever. The main approach is to store the content ...


12

I wrote four such books. My first one was 750 pages. The others ranged from 250-400 pages each. My technique was to budget a particular number of pages or a particular amount of time each day to write. For myself, I found that if I wrote more than about 4 pages per day (6 on a good day, it varied), I would quickly get burned out. That's 2000-3000 words. ...


12

Knowing who your audience is makes for a good first step. Writing end user documentation isn't the same as documenting an API, and shouldn't be approached the same way. Your audience defines everything that comes after, and how simply you need to present concepts. As Lauren noted, writing simply and plainly is solid advice, no matter who you audience is. ...


12

Have you considered (re)using Personas? A well defined persona can make it much clearer to talk about features as you remove a "layer of abstraction", making it easier for non-technical readers to understand. Your examples might change (with a little introduced context) from ... "Users will now be able to..." "...opens up the creation of $feature ...


12

It is one of the things that irritates me, the fact that users are so often considered "dumb". They are not. In many cases, they are more intelligent that the designers, it just may be that their skills are different. It is better to say that the users are not familiar with the technical issues involved. Or that the best UX solution is to make the front end ...


12

If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), ...


12

Since you're a software developer, I encourage you to think about the book the way you think about a significant application. You (probably) don't just start writing code; you do some requirements analysis, maybe some use-case analysis (please don't shatter my dreams :-) ), some high-level design... and then, if you're like most of us, you start ...


12

The European Union has a detailed guide to Writing for Translation (pdf). Some of the key points they cover: Use explanatory headings and summaries, and limit each paragraph to one idea Make sentence structure unambiguous Avoid long sentences with a complicated structure Use vertical lists Avoid empty verbs and ‘nominalisation disease’ Use the active ...


11

Users are usually categorized by their role, so you could write: "Managers will now be able to..." Also, some processes use a hypothetical first person to write about features, such as: "As a manager I should be able to..."


11

Of the three options that you offer, I'd say that #1 is the best. However, I'd suggest this as better yet: Worst of all, creation of a new node will return NULL when memory is full. Two things in particular to note: The adjunct clause when memory is full reads best at the end of the sentence. Trying to put it earlier requires that you set it off with ...


11

Introduction The Biggest reason documentation is written is to help developers learn about the software system and give them a reference to the tools they are using. This is a broad question and I must admit most of the tips I will give will be my opinions and things I've found helpful. Below are some guidelines and design aspects you can use to help ...


10

The classic answer comes from Strunk & White's The Elements of Style: Omit needless words. Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer ...


10

Emphasize effects over causes By this I mean don't lead your readers through the tall weeds, pointing out every individual weed. Walk them around the edge, showing them the size and shape of the field. Your non technical reader cares about and understands things like "the server crashed and the website was down for six seconds, resulting in a ten million ...


10

Short answer: no. Nevertheless, it's a plus. It is good to have a deep knowledge of the field you write about, so your documents have more weight and insight. I'd choose, given the same writing skill level, a person with technical background over one with no technical background, if what I'm looking for is technical documents. Why not have the edge, if ...



Only top voted, non community-wiki answers of a minimum length are eligible