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

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

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

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


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


6

The first step I would always recommend for any writing, but in particular for technical writing is to brainstorm and outline. Start by simply compiling a list of topics that you want to cover. Once you have that list begin putting them in a logical order. When you start putting them in order you will likely identify transition topics and support topics ...


6

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

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


5

Okay, let's do a cheat sheet. Be logical. When you describe the technology, describe it in an order that makes sense to the customer. Use a top-down approach, starting with an overview and delving in the details only when you have given the reader the context he needs to understand them. E.g. when you describe a machine, follow the flow of products ...


5

I agree with hildred's answer that a review of the basics is in order here: Sentence structure, grammar, and so on. There are no standards for general-interest articles, but academic papers do have such standards. Without knowing what, exactly, you want to write, it's hard to give you advice on structure. But I can give a few suggestions that might help ...


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

Ah, the "you can write in one context, so you must be an expert in writing in another context" fallacy. I've been on the receiving end of that too. Being a good academic writer, or engineering writer, or anything else doesn't mean you can automatically write good user-oriented material (or vice-versa). The person asking you to do this is making an ...


4

I would guess that most editors want readable copies of text, so either a printed version or a common file format such as PDF or Word. You can create both from (La)TeX. Wether or not a publisher will appreciate a .tex file after the manuscript as been accepted for publication by the editor will depend on the publishing process. Format: Scientific journals ...


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


3

The standard I found most common and probably most clear is to quote anything that appears on screen as fixed-width font on grey background. Using unicode right arrow → is the neat, elegant way to shortcut a traverse through interface. Open File → Preferences and pick the Advanced tab. Use the slider to adjust Allocated memory to 30MB and confirm with ...


3

LaTeX is fine as it will deliver a printable .pdf for initial approval to a publisher and many templates from scientific publishers, freely available from a basic web search can be loaded, including Springer and many others LaTeX templates Springer


3

The The rules surrounding the use of the definite article in English are quite complex and confusing for many non-native speakers. For example, 'the' is never used before a person's name unless for particular clarification: "Ron Howard's outside." "The Ron Howard? The famous director?" "Yep, that one." Nevertheless, I hear many non-native speakers use it ...


3

Disclaimer: I am not a native speaker I think these are two different questions. If you feel you use too many definite articles, that might mean your grammar is wrong. Try to think at every "the" you write whether you really mean to write about a specific object or if you mean to write about a more general case. I also notice many native speakers writing ...


3

"Persuasiveness" is highly subjective. I can't imagine how you would measure it other than to perform an experiment with real people. You didn't say what the subject of your paper is, which is probably good because that helps us to discuss the question of persuasiveness without being biased by whether or not we agree with you. I know of three basic ...


3

Some writers use these situations as an opportunity to embed small "Easter eggs," targeting your audience. For example, if your audience is in the UK and "geeky," Doctor Who references could work. In Australia, Mad Max references could work. This solution is not for everyone, but my usual developer audiences appreciate them, so long as they're subtle.


3

Assuming native speakers of American English: For first names: John Jack Mary Jane For last names: Doe Smith Jones Johnson Full names: John Doe is native English shorthand for "generic person." Richard Roe is native English legal shorthand for "second generic person in the same document as John Doe." ["Jane Roe" (an anonymous woman at the time) ...


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

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

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

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.


2

1) Put the descriptive text first, then the screenshot immediately afterwards. We read down. In the Print dialog box, click Export to PDF. [SCREENSHOT of dialog box] 2) You may or may not need a caption, but you should at least label each screenshot. Fig. 1, Screen B, Ralph, something. That allows you to refer to it elsewhere in the text.


2

An introductory text should always come before the screenshot that you are about to display. This will help the user to get an idea of what is about to be displayed in the screenshot. Then you can definitely provide the descriptive text for what exactly is happening in the screenshot for better understanding of the user.



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