Tag Info

Hot answers tagged

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

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

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

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


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

If this is user-facing documentation, then make up a data dictionary that describes the tables and columns with supplementary blurbs about the meaning of the data (e.g. the meanings of specific values in a column). This can be a straightforward HTML document with the supplementary descriptions as text. If you need to produce E/R diagrams then Visio ...


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


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

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

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

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

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

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


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

In test-driven development the emphasis is on writing tests that clarify what code should do, rather than extensive documentation. Future maintainers of the code can then ensure that the code continues to exhibit the behavior it should by virtue of the tests. The way tests are named form a type of documentation of the proper behavior of the code. Here is an ...


2

I don't understand this question. When you write an article, that article will have one theme or subject. Everything that your write within that article will relate to that theme, and therefore everything that you write will somehow relate to each other. Your writing must make that connection clear, and that is the purpose of what you call "transition ...



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