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.


10

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


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

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


6

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.


5

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


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

I've written manuals under a Scrum process, so I'll describe what worked for my team. I'm going to treat your task as if you're writing a new book. From your description, you'd be replacing the vast majority of the content anyway, so better to think of it as a new book (for which you might be able to take advantage of the occasional previously-written bit) ...


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


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


3

As a software developer (C#, .NET, yada, yada), Monica's answer resounded nicely with me. (I don't have enough rep yet to comment on it, so my additions have to go here.) I would add that I find great value in API documentation that is as explicit as it can be, but not overburdened with meaningless details. Further, it's very important to me that the ...


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

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

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

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


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


2

Ask your readers to point you to API documentation that they do find helpful. Get clarification from your readers. Do they mean that the "javadoc" is too vague? incomplete? poorly worded? Or do they mean that they can understand the reference doc, but it doesn't help them write an application using the API. Here's my edit of the original example. I had to ...



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