Tag Info

Hot answers tagged

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


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

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


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


9

For internal documentation I've found wikis to be quite useful. A wiki has several useful features for this task: built-in change-tracking doc can be structured as several pages (e.g. one per major section) for easier management; individual pages can then be edited without any need to merge changes into a master document some (most?) wiki platforms detect ...


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


7

Unless the figure is central to both problems discussed and quite a bit away in text from both, avoid this. If the figure is, say, 2-4 pages back (not forward. Introduce it with first reference, then backreference. Don't make forward references) just reference it by name, "Figure X from page Y", don't copy. If the second occurrence is chapters away but ...


7

Let's break down your illustrative sentence: Users can delete Servers This statement describes a capability -- users can perform this action. I'm hard-pressed to imagine how a different tense could be used here. Some technical writers (or style guides) make this overly passive -- "the system supports user deletion of servers" or some such. Speaking ...


6

The Chicago Manual of Style says that the inclusion or omission of a leading 0 depends on whether quantity could be greater than 1. If the quantity could be greater than than 1, include the leading 0. Especially if quantities greater than 1 appear in the same context. For quantities that are always less than 1, it is typical to omit the leading 0. CMoS ...


6

It's not that it's unsuitable, but the word play of "Ins and Outs" isn't very well matched with the subject of "Boolean Variables." "Ins and Outs" sounds like it's more about GPIO pins. I'd be tempted to do something like; "If This_Chapter == About_Boolean_Variables {Read}" ;)


6

An informal, jokey title is perfectly appropriate. This is especially true if, as I surmise, you're writing a progrmming manual of some sort. Computer science is a pretty informal field, after all. It's almost expected. The title isn't very eye-catching, but it's a common enough turn of phrase and there's nothing wrong with it, as such.


5

I've seen this done with a "watermark" that says (usually) "sample data" (kind of like this, from here, though that's a table rather than a chart). Think of the "draft" watermark you sometimes see on documents; same idea. Saying something in the text (or figure caption) can be helpful, but this approach has the advantage of embedding the information ...


4

If this is user-facing documentation, then make up a data dictionary that describes the tables and columns with supplementary blurbs about the meaning of the data (e.g. the meanings of specific values in a column). This can be a straightforward HTML document with the supplementary descriptions as text. If you need to produce E/R diagrams then Visio ...


4

I've written manuals under a Scrum process, so I'll describe what worked for my team. I'm going to treat your task as if you're writing a new book. From your description, you'd be replacing the vast majority of the content anyway, so better to think of it as a new book (for which you might be able to take advantage of the occasional previously-written bit) ...


4

As Lauren loves Scrivener I love LaTeX! It lets you code your books, build reusable modules and makes laying out text a breeze. Writelatex.com is an amazing free site that lets you work with LaTeX online, work collaboratively and save your documents as Zips or PDFs. We use it to write the rulebooks for our tabletop games and RPG systems; we have a template ...


4

Two classical typewriter methods are White-space and the Horizontal Rule. On the other hand, verbal transitions have significant value, in that they are clearer than simple formatting. I get the impression that your main objection is the feeling that they contribute to the cliche of the format (you read one self help book, you know how they all are ...


4

I often run into this problem too. I think in the end it usually sounds redundant anyways but I use phrases like "the data suggest" or "the results suggest" in the discussion and in the introduction I usually just state the claim without attributing it to myself since it's assumed it is "this study" (unless it's cited information). You don't technically have ...


4

You can't guarantee the reader will make sense of your translated text without a layer of human intervention. If anything, you should have two: one who is an expert in the field, to make sure content wasn't lost in translation, and one to read for native-language coherence. Translating text is not like changing fonts. You must have a human read it at some ...


4

You can write the FAQ in a mixed fashion. Depending on what the actual question is, you could choose any of the three styles (or maybe alternate styles too) that you have mentioned to frame that particular question. The idea should be that the readers find it useful. If it is something obvious, then the style differences might not be too much of a deal. For ...


4

Title: Meaningful but not overly long Rendering 1500 Users Helpless: An IT Project Report Abstract: Summarize the report in one paragraph Problem. Management Fix. IT Implementation. User Reception. Coverup. Sec. 1, Introduction: Give background on the project. (What led to it?) The recent release of Win8 with its BadIphone interface has ...


3

I've done this in a number of documents, where I state clearly that it is "illustrative" or "used to demonstrate a concept and the rough proportions of one item to another. I've found I have the least amount of confusion by stating in the paragraph just before the chart appears, and then stating in the graph somehow.


3

You say it's a sales document, aimed at engineers. In that case, describing every part of your process in detail -- including the non-unique ones -- seems to me both unnecessary and counterproductive. Your readers will get bored out of their minds, will start skimming through your document, and will probably miss the unique aspects of your process. ...


3

I'll answer this question from an uncommon perspective. The Publication Manual of the American Psychological Association (APA) recommends that you do not use the ™ or ® symbols but requires that you capitalize trade and brand names (2009, p. 102-103). If a whole science can do without these symbols, so can you. If you are unsure, look how respectable ...


3

The other answers are correct to say that you need to read a lot. But it's not enough just to read. You have to read like a writer. Anytime you read a passage that is particularly clear or compelling, stop and try to figure out what made it so. Later, try to mimic that style in your own work. When choosing what to read, look for writers who are masters of ...


3

Writer's block is probably part of it, but another part is just knowing how to make ideas and words flow grammatically. I noticed you had a few minor mistakes in grammar, such as that you should have said, "when it comes to speaking in English," and "I consider myself to be at an intermediate level." (Although I would've said "I think I'm at an..." because ...


3

Trying to avoid the word "I" often leads to convoluted prose. The active voice and use of "I" result in easy-to-read, unambiguous sentences. So unless the style guide of your university forbids the use of "I", I wouldn't worry and use the active voice. Here's an example of a thesis style guide that recommends the use of active voice.


3

In the absence of a style guide saying otherwise, your approach is fine. (So is abbreviating to "Fig.", though I prefer to spend the extra three letters and use the full word. It's also consistent with "Table", which I haven't seen abbreviated as "Tab.".) Whatever you do, be consistent -- refer to all of your figures as "Figure N" and use that same text ...


3

As a software developer (C#, .NET, yada, yada), Monica's answer resounded nicely with me. (I don't have enough rep yet to comment on it, so my additions have to go here.) I would add that I find great value in API documentation that is as explicit as it can be, but not overburdened with meaningless details. Further, it's very important to me that the ...


3

DITA is an XML format, so any editor or IDE that supports XML will work for you. Options with good XML support range from Eclipse (free) to Oxygen and Epic (several hundred dollars per seat). Of course, anybody who's comfortable getting up close and personal with the XML can use Emacs, vim, or Notepad++, too. (Don't laugh; I write all my XML and HTML in ...



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