A few remarks on how to write articles (not yet a real style guide)

(Note that ‘article’ here means any kind of contribution.)

General hints

  • Wiki contributions should ideally be readable on-screen. Thus, writing consisely is often preferred. Sometimes longer articles can be split into several contributions. For example, when discussing how to implement a specific optimisation method, describing how constraints can be handled may easily warrant an article of its own.
  • Always finish an article in one session. This does not mean that articles need to be complete and cannot be changed or enhanced later on. (Quite the contrary, actually.) But when you decide to put a piece of work onto the Wiki, do not leave it as a ‘construction site’, but finish it so far that the basic idea is stated. A good way to prepare contributions is probably to write them in an offline text-editor and then copy/paste them into the Wiki. In fact, since $\LaTeX$ formulas can be used, very often tex-files can, more or less easily, be converted into the markup language of Wikidot.
  • Wikidot does not offer spelling checks. If you rely on those, it is advisable to first write your contributions in an offline text-editor.
  • A very general hint: read all you can, and try to be conscious how other authors formulate or use certain elements of style. (If you need ‘inspiration’ how whole research papers can be shrunk to one or two pages, have a look at the contributions at VOX. These may have nothing to do with your research, but they give an idea how to write.)
  • Another general remark: styles guides are just that, ‘guides’. Whenever you have good reason to consider some ‘rule’ not appropriate, override it.

Grammar and Spelling

The main emphasis of this wiki is on technical correctness, not style correctness. Hence, there is little need for fancy-looking gadgets if they are not necessary. That said, certain style elements will clearly help the reader (if you have ever read a book full of maths written with a typewriter, you know what this means).

American vs British English

There are actually more differences between American and British English than the non-English speaker may think. (If you are really interested, see the Print edition of The Economist's Style Guide.) For this Wiki, however, the differences are probably less important. As was pointed out above, emphasis is put on technical correctness. If you know about the differences, however, try to stay consistent within an article (e.g., do not switch between -ise and -ize).

Library

Many articles will require to cite published papers or books. To keep the bibliographies consistent, here is a collection of references used so far. Click here>>.

Pseudocode

How to write pseudocode in $\LaTeX{}\,$ and include it into pages is described. Click here>>.

Formats

Headers

Use the predefined headline formats (+, ++, …). When numbering headlines, do not put a period after the last number. That is, write ‘3.1 The model’ instead of ‘3.1. The model’. Note that the section header (with a single ‘+’) is underlined automatically.

Internal Links

Concepts
Tutorials
Tips
Related Articles

External links

References
1. Higham, N. J. (1998). Handbook of Writing for the Mathematical Sciences. Cambridge University Press.
Weblinks
The BBC News Style Guide
The Economist Style Guide
Wikipedia Style Guide
`Writing tips for PhD students.' by John H. Cochrane.

for COMISEF members: Thomas Wagner's English lectures

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License