Hot answers tagged technical-writing
30
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, ...
21
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 ...
19
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, ...
17
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
...
16
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, ...
15
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 ...
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 ...
13
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 ...
12
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
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 ...
11
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 ...
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
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 ...
10
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. ...
10
Firstly, it's always a good idea to clearly indicate whether the message reflects an actual error, or simply a warning which the user may choose to ignore.
Secondly, try to minimise use of "jargon" terms such as translate, higher precedence, and overrides.
Warning: The 'name1' concept1 is assumed to be a type of 'name3' concept3, not a 'name2' concept2.
...
10
There are two general approaches, depending on the amount of detail you need from the "other" concept.
If you don't need a lot, write about subject A, and when the first interaction with B hits add a parenthetical sentence, call-out note, or footnote (depending on your style guide) describing the other concept and pointing to its main documentation. For ...
9
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 ...
9
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 ...
9
There are different kinds of technical writing, differing in the "technical" part. The logical place for you to start, coming from a programming background like I did, would be with programmer-facing documentation: APIs, SDKs, and the tutorials and guides that go with them.
If any of your current (programming) work could benefit from either external ...
9
There's a problem here: Saying something like, "users are stupid," makes you look ignorant.
As other have said, the fault isn't always with the user; sometimes, a product is poorly designed. And, even though some users will search frantically for the "ANY" key, many other users are proficient, not dumb.
I realize you mean the statement tongue-in-cheek, but ...
8
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 ...
8
In response to Is it coherent? and Is there an overall sense of clarity?, I think you've got a lot of problems that boil down to simple formatting, spellchecking, and proofreading. These make the piece much more difficult to read and understand. Among the problems I noticed:
You should use a spell checker. "atleast" is not a word, "I" is upper-case, and ...
7
Sorry, but about all I can say is: it varies.
Is there a particular publisher/series this is for? That would help me give a general estimate. For instance, it should take less time to (imo) write a page for a Dummies book than a Head First book.
In addition to your list, I really tend to burn up hours in two other areas:
Research
What do people commonly ...
7
You can engage your writing with other writers by not just having your own blog, and hoping others will comment there, but to seek out other blogs of interest written by others, and comment there as well. If you have useful and interesting things to say, this can act to draw people back to your own "personal corner of the web" -- still the commenting is more ...
7
The answer depends a lot on what you have around you and what your needs are; assuming that
You don't have extensive needs beyond Latin-1 and Math character sets, or simple use of Unicode character sets
You don't have a need for overly-rich or complex page layouts (i.e. you're not doing page layouts that you'd see in a glossy magazine)
You don't have ...
7
Nothing to do with intelligence
I would instead write something like this.
You should try to make it obvious how to use your app, recognizing
that it is there to serve the user. Imagine a brain
surgeon trying to use Skype to consult with a colleague. This user has
limited time and attention. She does not want to
spend 30 seconds figuring out ...
6
The following is based on both the content of your question, the way it was written, and your comment on your question.
Your primary problem is not editing. Editing is your third biggest problem, Writing is the second, and your biggest problem by far is Organizing (and Developing) Your Thoughts.
Organizing your thoughts
I can tell from your writing style ...
6
Be clear. Write simply and plainly. Define your jargon and your acronyms, even if you think everyone knows them already, and use jargon as sparingly as you can.
Imagine handing your document to someone outside your field (or better yet, try to get an editor outside your field) and aim for your work to make some kind of sense to that person. Obviously an ...
6
I'm not an expert, but my understanding is that technical reports are generally written in the passive voice. So, unless there's a reason to use first person, I'd avoid it.
That said, I think it's pretty rare that you'd be called upon to write a spontaneous, context-free technical report, so I'm with user1594 in thinking that you need to look at the ...
6
Rather than formal training, consider getting involved with the doc team of an open source project with a strong commitment to the quality of their technical writing.
You'll get not just one teacher's eyes on your work, but several to dozens of experienced technical writers.
You'll get feedback from consumers of your technical writing.
You'll have a ...
Only top voted, non community-wiki answers of a minimum length are eligible
