Tag Info

Hot answers tagged

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


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

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.


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


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


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

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

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

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


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

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

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

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

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

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

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


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

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

The Style Manual of the American Psychological Association (APA, 2009, pp. 104-106) is very clear on the use of italics. Note especially the bold section (bold emphasis mine): Use italics for titles of books, periodicals, films exception: italic words in the title (reverse italicization) genera, species, and varietes introduction of a new ...


2

My previous company faced this issue in many situations. They handled it in several ways: The company registered a domain name, so that we could use it as an example domain in URLs. For names, we used characters from famous works of fiction. My favorite was Elizabeth Bennett. I also used famous authors, like Emily Dickinson. For addresses, I used the ...


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


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

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

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