12

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


12

Python has a useful module called doctest. It is commonly used to validate tutorial documentation and examples embedded as comments in the code. The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use ...


8

Some writers use these situations as an opportunity to embed small "Easter eggs," targeting your audience. For example, if your audience is in the UK and "geeky," Doctor Who references could work. In Australia, Mad Max references could work. This solution is not for everyone, but my usual developer audiences appreciate them, so long as they're subtle.


8

Assuming native speakers of American English: For first names: John Jack Mary Jane For last names: Doe Smith Jones Johnson Full names: John Doe is native English shorthand for "generic person." Richard Roe is native English legal shorthand for "second generic person in the same document as John Doe." ["Jane Roe" (an anonymous woman at the time) is the ...


6

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

Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlooks the fact that API documentation is used by a range of people. It's short sighted by both the guys who says it and for the writing team to assume the documentation is only for the experienced developers. It has to appeal to both the ...


4

I can understand the reasoning from both sides. A complete quick start is essential to ensure that the reader has sufficient information to see the product running correctly, and is able to demonstrate and present a sample default use case to the user, without these the casual reader will not know whether to bother reading further because they will be unable ...


4

The value of adding code examples to documentation depends on the example itself as well as the API or library in question. I work with a widely used software library, and we have a stated expectation that our users are well beyond the "Hello, World!" level. We have examples and guides that build components incrementally, where each part is self contained ...


4

"E.g." is an abbreviation for the Latin "exempli gratia", which means "for example". The abbreviation is fairly common in "advanced" writing, like theses, in my experience. However, it's an other-language abbreviation, so it's a small hurdle for some. Might your thesis have readers who are less advanced? Might some of them be weaker with English than you ...


3

They mean exactly the same thing. Outside of cases where you must following a specific manual of style, if the writing is formal, it's up to you. You should, however (according to Strunk), place e.g. inside a pair of commas, e.g., here.


3

Yes, there are many. You can find them quoted in scriptwriting textbooks. For instance, Linda Seger in her famous book Making a good script great cites The witness by E. Wallace and W. Kelley as a paradigm of a good script. Every book about scriptwriting contains many examples of "good scripts". There may not be a universal consensus, but those examples ...


3

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


3

Take great care when you opt to use a single generic name (or even a limited set). What is the message you are sending to Trang, Luigi and Antwan when every reference to a given name uses John or Richard? Are you certain that your target audience is so ethnically homogeneous that they will all identify with Dick and Jane from Picket Fence Lane in Smalltown? ...


3

Speaking as a programmer, the solution to your problem is "don't be lazy." Taking screenshots is easy but risks libeling others: It can include their logo, their product picture, their address and phone number, and they can argue that your criticism is costing them money, reputation and good will. However, if you are writing something for professionals ...


3

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


3

One suggestion is to solve the problem outside of the IDE, and inside your versioning tool. If you check in your documentation along with your source code to the same repository, then you can use command-line tools like 'git grep' to refactor code + docs at the same time.


3

I mostly agree with Lauren Ipsum, just a couple of extra thoughts: As Lauren says, John Doe and Jane Doe are widely recognized as fake names. John Q Customer is often used for a fake customer name. For US telephone numbers, use "555" for the exchange, like "123-555-1234". "555" is reserved by the phone companies just for use in examples and in books and ...


2

There are several projects that come to mind that seem to do this well. All of them use very similar techniques. One is the Qt framework, another is a tool called Doxygen, and a third is the GTK+ Project. In all three cases, the documentation for the project is primarily pulled out of the actual source code for the project. The both are maintained ...


2

I would actually answer this with my graphic designer hat on: all code should be given a particular style in the layout program (font in particular, but type size, margins, justification), and then you just Search for each iteration of that style. It's still manual, but you won't miss any.


2

There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes too simple (simplistic), but this example should use defaults where possible and not bite off too much --...


2

The purpose of API documentation is to explain how to use the API. Providing sample code of how to use key features is a good way to demonstrate the intended usage. A good example of this is the ZMQ guide. It has example code in a large number of languages to go with each of the of the concepts discussed. They combat the bloat by displaying links to the ...


2

Do not get panicked in emergencies. is okay. But whether you want to write it that way is a second point. Why not simply say: Do not panic in emergencies. It says the same, and it's easier to read.


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 can find nothing to indicate that e.g. (or 'for example') should be left out of a thesis, or any other body of writing. If you do, however, want to use a different indicator then 'such as' is a good, formal alternative. It is possible to use 'like' in some contexts, but this is a more informal mode of expression and should probably not be used in a thesis....


1

I like the third version, without colons, because the visual break and the code formatting makes it clear that this is a new "clause," or thought, and the piece of code is not a grammatically correct full sentence. Since you are continuing one sentence over several breaks, I wouldn't use capitals. I think Watercleave has another good solution if you can't ...


1

Even "fair use" doesn't cover the reaction of the owner and won't protect the intent of the user. As my retired attorney father often said, "anyone can sue anybody for anything at any time." If you will always praise the websites. I.E., "This website is a great example of rule #6..." then screenshots probably can be used under "fair use" and it's unlikely ...


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