Tag Info

Hot answers tagged

33

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


33

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

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

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.


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

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

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


10

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


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


10

Unless you have a very good reason not to, you should include the leading zero. The combination of leading zero and decimal point is far more recognizable than the decimal point by itself.


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

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

Python has a useful module called doctest. It is commonly used to validate tutorial documentation and examples embedded as comments in the code. The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use ...


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


9

Start with the style guidelines from Oracle for Javadoc. While those guidelines are written for the Javadoc tool (and the Java language) in particular, the principles there apply to the corresponding tools for other languages. (I've seen this kind of documentation for C++, C#, and JavaScript APIs.) This answer augments that style guide. I'm going to ...



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