ATLAS Writing Style Guide

22 September 2008


In the coming years, Muriel like the rest of the ATLAS collaborators will write many documents, making John Ellis' piles much bigger...


In the coming years, ATLAS will be writing hundreds of scientific papers, as well as many internal and external notes and reports. We want these to be clear and easy to understand. If they are well written and prepared, it will also reduce the editing time and effort needed. But many people in ATLAS do not have much experience in writing papers, or will not be writing in their native language. The authors of the papers and other documents (even the experts!) will need guidance and help.

Previous ATLAS Publications Committee documentation already included a short ‘style’ section, giving some advice on how to write papers. However, this covered only a very limited range of topics. “PubComm” decided that a separate, more complete guide would be useful, and I was asked to write it. The resulting ATLAS Style Guide has now been approved as ATL-GEN-PUB-2008-001, and it is available on CDS and from the PubComm web page.

The Guide covers a wide range of topics, some of them at more advanced levels than others so that it will be useful to experts as well as the less experienced, and to both native and non-native English speakers. It is not necessarily meant to be read from end to end (although of course you can!), but more as something to refer to when you need specific information or recommendations. The format is PDF, so that everyone can read it easily with free software. There are internal links and bookmarks for jumping to referenced sections, as well as hyperlinks to referenced web pages. With experience and use, the Guide can and should evolve, so please send me corrections, comments, and suggestions on what could be added or improved.

The Guide makes many recommendations regarding ATLAS style. There are numerous examples, oriented towards particle physics wherever possible. However, in writing papers there are many grey areas where there are no clear rules. Hyphenation is a notorious example, and in such cases the Guide is not prescriptive – it gives information and advice but does not ‘lay down the law’. It does, however, stress that whatever choices are made, it is essential to apply them consistently, and that the journal’s own rules must be respected.

On the ‘hot’ question of tools for writing papers, the Guide covers both LaTeX and Word (or similar open-office word processors), since both have good and bad points. There are tips and comments throughout the Guide on how to do things with both. The Guide does not mandate which one to use, since not everyone would agree to that. For example, some people told me ‘it is impossible to write a serious paper in Word’, while others said ‘LaTeX is completely out of date’. Neither of these statements is correct, and the choice depends on taste, expertise, and the nature of the document being written.

So what is in the Guide? It starts with the basic rules of doing things consistently and following the rules of the journal. There is a brief description of the main sections to include in a typical paper, and what they should normally include. There are general guidelines for figures and tables, including some advice on graphics formats, on making clear drawings and graphs, and page layout. References and how to format them are discussed.

The organization of sections and subsections, and the use of styles to make editing the document easier, are described. This leads into a discussion of typography, including fonts, numbers, variables and symbols, subscripts and superscripts, and several more detailed items. Units, equations, lists, italics and bold type, etc. are also covered.

The next section describes the pros and cons of using both Word and LaTeX, both for general information and to help anyone who is not sure which one to use in making the choice.

The last main section concerns English usage. After some important general points, there is a detailed section on the differences between American and British spelling – important since most recommended journals for CERN publications prefer British English. Then there are sections on capitalization, hyphenation, and punctuation. Finally, there are some miscellaneous items, including common mistakes made by both native and non-native English speakers. The Guide does not, however, try to be a complete guide to grammar, since that would require a huge document and there are many excellent books available.

The appendices to the Guide include a compilation of units and their standard symbols. The glossary that featured in early editions has now become a standalone Twiki after combining it with several others, notably the one in the Software Workbook, to create one overall ATLAS glossary. It defines acronyms and other ATLAS terminology, and at the same time recommends how to write them. As a Twiki, people will be able to add or update entries, making it more useful.

For LaTeX users, independently from the Guide, there is a very useful ATLAS macros file. It defines commands for generating a huge number of common variables and symbols for particles, from the simplest to the most exotic. It has been built up over many years by a number of people. Using these macros can save a lot of tricky work and ensures consistency. I have tested all the macros in this file, and made some detailed changes so that it is consistent with the recommendations of the Style Guide. This file may be found here or by starting from the Publication Committee website.

So all we need now is to get results and we can start writing!

Eric Eisenhandler

Queen Mary University of London