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


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


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

You probably should join a writers group where you can get reviews and feedback for your writing, and support from other writers. In your question I noticed at least one grammar error in every sentence, so I would recommend reviewing the basics: sentence structure, verbals, and punctuation.


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


5

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}" ;)


5

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.


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

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

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

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

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

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



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