Hot answers tagged

8

Your question title is very general, and your specific question is about the pervasiveness of the Oxford comma, and wanting to give up all lists because no one agrees. I suggest that "pervasive" depends on the type of writing (book, science, academic, or news) and--rather than give up on lists--you decide on your style guide and then handle exceptions to it ...


6

Consider incorporating your fine print into the body of the article. Nothing in your Fine Print section requires any special understanding of the science involved, or even a good understanding of how science proceeds. As a bonus: If you do that, you can drop the opening part of that section, which is about you, and not about the topic. If the authors' ...


5

In my opinion, any answer looks messy. One "sentence" with capitals halfway through bugs me; so does a line starting without a capital. Personally, I would restructure the entire thing to avoid the issue entirely: Example 1 Currently, line 57 of camera.py looks like this: camera.start_recording('foo.h264', quantization=25) In this line, the ...


5

LATEX isn't a text editor, it is (broadly defined) a markup language. The alternatives would be things like markdown, asciidoc, docbook, or simply using HTML directly, in tandem with your favorite plain text editor. Docbook and HTML are "heavyweight" markup languages (you need a tag for every paragraph, etc), whereas markdown and asciidoc are lighter and ...


5

I think MS Word and Open Office would be the obvious candidates. MS Word pretty much dominates the market. Open Office is there for people who just want to rebel against Microsoft. I'd need a very good reason to use anything else, as to function in a Western business, government, or academic environment these days you pretty much have to use MS Word at some ...


5

Instead of "fiction" (made up) and "non-fiction" (facts) I'll use the terms "novel" and "textbook". We expect a novel, both fiction and non-fiction, to be about experience and possibly ideas, and textbooks to be about detailed information. But there are countless counter examples. For example the scholarly field of ethnology often employs first person ...


5

When I'm editing technical documentation (and, ideally, when I'm writing it in the first place), I try to make every word earn its place. If both words in your phrases need to be there to make your point, then don't worry about it -- that's not a tic but the writing process. In the case of pairs (or larger groups) of descriptive adjectives or nouns, ...


5

I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of "keyboard input", you'd use that unless there's a good ...


4

Don't Minimize the uncertainty, celebrate it! Sensational science reporting does not worry about details just bold headlines: 'Cell Phones Cause Breast Cancer!' Responsible reporting hedges their bets: 'Link between Cell phone usage and Breast Cancer Found.' Great reporting shows what the details mean: 'Developed nations have more cell phones and breast ...


4

I am not a lawyer and this is not legal advice. First, check any license terms that accompany Company S's documentation. They might have published it with the intention that other vendors will incorporate it (e.g. some Apache platforms), or they might not intend that but allow it under their license (e.g. Stack Exchange, or anything else that uses the ...


4

Active voice is the appropriate choice for all types and sections of technical documentation, and for training and service manuals. The Microsoft Manual of Style is used by professional technical writers. The 4th edition (2012) says: In general, use active voice. Active voice emphasizes the person or thing performing the action. It's more direct than ...


4

I don't think the trouble lies in either choice, since neither is inherently better than the other (though some could argue that the two-sentences version has more clarity). Rather, you may want to be begin with a simple context-setting sentence. Since this is a technical document, consider first mentioning that there are several ways to approach data ...


4

A longer post can work on a blog that usually tends toward shorter posts if you take some care in structuring it. "Here are 20,000 words, plus equations" may send some people to the "back" button right off, but a five-minute introduction followed by an expansion can satisfy both audiences -- those looking for the high-level information and those interested ...


3

Whatever results in the less convoluted and easier to understand syntax. Usually people find it easier to understand active voice. Even research articles are today usually written in active voice and avoid confusing self-reference-avoidance (do: "We conducted a study...", don't: "A study was conducted ..." [by whom?]). Machines are operated by persons, they ...


3

This is a decision you need to make in consultation with your company's legal advisors. The ability to defend against claims is affected by both what the warranty says and how prominent it is. A separate document or appendix that people are less likely to read might cause problems in this area. (Never mind that users are trained to skip past all that ...


3

First, ask yourself if all the illustrations are necessary (i.e. are these screen captures illustrating a screen with one button on them?). The reader is going to be very annoyed having to flip back and forth between the procedure and the diagram. I don't have any links to show you for that, but I've done actual testing with users and the overwhelming ...


3

I think about the, "This is only the beginning" concept more as "This is the first step". It is very common in academia to think about your PhD as a stepping stone to your initial body of research over the next few years. I would think the ideas in the "next steps" paragraph need to be fleshed out in more detail. (Use the "If you could wave a wand and have a ...


3

Often there is a difference between a thesis, as it is submitted to the examination board, and the book, as it is published. The version that you submit to the board of examiners must comply with the academic rules of your discipline. It will usually be written for an audience of experts. Ph.D. theses have to be published, but today you can publish it ...


3

There's nothing confusing about the paragraph you have at the end. Given the replication rates for correlation-based studies, there no reason for the reader to believe that the study established a new insight into the effects of trans fats. A layperson shouldn't base his idea of the effect of trans fats on a single correlational study based on self ...


3

I would say write what you are capable of. If your talents are non-fiction, straight to the point works then definitely write it that way. But if you are very skilled at writing fiction stories detailing adventures or thought-provoking ideas, then do that. Personally, I would write a fiction novel detailing all the technical experience of advanced diving ...


3

It seems to me to mostly depend on your target audience. Scientists of this field will want full throttle facts, General scientific types will expect to be convinced by strong backable data Interested non-scientists may relate more to argument that make sense and are logical rather than specific proof, The general skeptic reader will not trust any ...


3

I think the approach to this is to make what you write entertaining. Try to keep the style light, so you're not overwhelming the reader with facts. Use a steady build up, make the first few chapters skipable by someone who understands the field, but allows the layman to grasp the basics of where you're going. Keep the obvious stuff at the beginning, with ...


3

Circumlocution. Locution that circles around a specific idea with multiple words rather than directly evoking it with fewer and apter words. Check the wiki article here. Update As an author, you'll sometimes want to use those either to avoid repetition (some sentences have the tendency to come out more often than you'd like), or specifically to ...


3

DevonThink. Look here: http://www.organizingcreativity.com/2015/02/digital-information-infrastructure-with-devonthink/ Also google stuff like "academic writing workflow" or "science writing workflow" or a combination of "workflow" with a specific software, either for writing (Scrivener) or citations (Zotero) -- there are quite a few blog posts where ...


3

This doesn't seem to me like a serious problem, it's just a part of your own personal writing style. Even in technical writing, you don't necessarily want to edit all individuality out of what you produce. My advice would be only to resist the impulse to add this in places where it isn't really necessary or helpful. Personally, I like your parallelism. ...


3

Not overkill at all. However, the Chicago Manual of Style is not really ideal for technical writing. It is a good guide to general, formal writing for Americans. For a more international audience, the equivalent is The Oxford Guide to Style (a.k.a. New Hart's Rules, also published as half of Oxford Style Manual). The principal problem with Chicago is that ...


3

Using "he/his" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people. What I do is to write around the problem wherever possible. First off, if you're referring to the user of your API, it's better to write in second person imperative anyway -- "do this, then do that". ...


3

Wikipedia has this short list of graphical elements for interfaces that use the prevailing WIMP paradigm. https://en.wikipedia.org/wiki/List_of_graphical_user_interface_elements According to the example you've provided above, I think what you have there is a zoomable popup control or zoomable popup widget Hope this helps! Personally I've never liked ...


2

ReadTheDocs (a popular system for documenting code-bases) has an interesting feature which may provide an answer to this question: literalinclude. With this directive, one can include code examples from another file within the documentation. The particularly interesting part is that a subset of lines can be extracted from the source file via the :lines: ...


2

I am not specifically familiar with that book, but as much as I hate to admit it (I am not fond of microsoft) they tend to do these things well. The two pieces advice I would give you are to supplement with a traditional style guide like Chicago, and document where you draw each standard from; and to feel free to set your own style for things where the style ...



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