Tag Info

Hot answers tagged

30

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 ...


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, ...


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 ...


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, ...


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 ...


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 ...


15

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 ...


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

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

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. ...


11

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. ...


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

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 ...


10

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 ...


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 ...


9

In everyday writing, (say on the web, or an email) I'd use bullets where possible. I think they're more accessible and quicker to scan. Unless there were some reason to actually number things. The Wikipedia style manual spells this out well: Use numbers rather than bullets only if: A need to refer to the elements by number may arise; The ...


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

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 ...


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 ...


8

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), ...


8

Let me add some tips regarding computer translation, although I believe Rob Hoare's answer is great: Write the original in a 'popular' language for the simple reason that those are most tested and most optimized. If for example you will be using Google Translate then it's mostly like the the node distance to any language is smallest from English (or maybe ...



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