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


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

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


8

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


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

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


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


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


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

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

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

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


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


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


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

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

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

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

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



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