Tag Info

Hot answers tagged

7

No, is not needed capitalize a word after a colon. Same as spanish. I want the following: butter, sugar, and flour. Read here the rules: http://www.grammarbook.com/punctuation/colons.asp


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

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

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


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

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

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

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


4

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


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

In an agile project with a diversified team, there are two primary purposes for documentation. Both of them are detrimental to the software development process. As Benjamin noted, there is documentation targeted at the users (both developer and non-developer level). These documents will focus on the functionality of the project and the interfaces which it ...


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


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

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

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

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

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


2

Steven Pinker recently published a book called The Sense of Style. It's intended to help competent writers of nonfiction become good writers, and addresses these types of questions. You should also try the classic The Elements of Style by Strunk & White, which is smaller and simpler, but about a century out of date. Nonetheless, most people will tell ...


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

May I recommend an approach I use since I also license my content for reuse: Source - HTML source format is my preference, but you can use LaTex as well Works great for all your distribution formats - PDF, Mobi, Word, etc Google Web Designer - Editor for all major OS's http://www.google.com/webdesigner Love this line from License agreement - You retain ...


2

I use several methods depending on the situation: when a client reviews my work, I supply them with a PDF and ask them to use the Acrobat commenting tools to insert the comments and changes. Then I can go through the list and add checkmarks to the comments I've processed. Acrobat can filter these, giving me a list of comments I haven't done yet. You can ...


2

As a rule using excerpts for critical or explanatory purposes is fair use. As long as the excerpts are fragmentary and clearly essential to your criticism you should be on solid ground. The main thing to avoid would be copying large or complete sections of the web sites or copying things which are irrelevant to your own material.



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