Writing in the nLab should be a pleasant and rewarding experience. We are always glad for new people to join us in this collective effort, bringing their expertise to bear on the many topics touched on at this site. Many contributors put in a considerable amount of work to improving the nLab, and all such efforts are greatly appreciated.
However, the success of this project also depends in great degree on a certain ethos of cooperation and mutual respect that has evolved here. This page is meant to lay out some of the working principles that have helped to foster this atmosphere.
Before reading this page, you should have read or at least be aware of companion introductory nLab pages such as nPOV, About, and How to get started and HowTo (the last being especially useful for editing techniques). This page is meant to help smooth over possible misunderstandings that may arise about the nature of the project, and to help newcomers to nLab writing fit in more readily.
Perhaps the one overarching piece of advice we can impart to newcomers, which applies generally outside the nLab as well, can be condensed into a single principle (a form of the “prime directive”):
Let the mathematics, physics, and philosophy speak for itself; try to get your own self out of the way.
The purpose of the community of nLab editors is to maximize insight, both for other members of that community and for others readers, and largely from a particular point of view called the nPOV, as well as from the string theory point of view for physics related articles. When joining that community, your purpose should be the same. The existing community has found that this happens best in an atmosphere where we minimize distractions and help keep ourselves and our readers focused on the big picture. This advice may seem obvious, but there is a bit more to it than may appear at first glance, and so we elaborate on it below.
While scientific results are recorded or archived at the nLab, and undergo further polishing and revision there, the principal organ of communication we have is the nForum. A basic rule is that
With few exceptions, all edits to the nLab (either the creation of a new page or the revision of an extant one) should be announced at the nForum, in the “Latest Changes” category.
The only real exceptions are very minor edits such as correction of spelling mistakes or obvious typos or indisputable grammatical errors. However, because of this rule there can at times be a large volume of Latest Changes posts; thus a corollary is that Latest Changes posts at the forum should generally be kept very short and to the point. They should also include a link to the nLab page in question (links at the nForum are created with the same <a class='existingWikiWord' href='/nlab/show/syntax'>syntax</a> as on the nLab itself).
The nForum is also home to wide-ranging discussion of scientific matters related to this project, and we encourage newcomers to join these conversations as well and get to know the existing members of the community. We ask each other questions and suggest ideas; then when those ideas yield fruit, we often record the results back in the nLab.
The genesis of every article is recorded in a revision history. Thus every contributor gets some credit (the name or alias of each contributor is shown at the bottom of each of their revisions, and the changes introduced by each revision are also faithfully recorded). But the nLab belongs to us all. Speaking optimistically, we could liken the nLab to one of the great cathedrals of Europe, where unnamed architects and artisans worked together to build a monument to a glory far surpassing that of any one individual. Feeling oneself as part of such a collective project can be a great reward.
There is a uniform Joker name applied to those who don’t perform an edit under their own names: “Anonymous”. (This was originally “Anonymous Coward”, a joke.) An edit attributed to “Anonymous” could be a case of someone who didn’t submit under their real name because they forgot, or it could be someone who has good reason not to submit under their real name – whatever. It’s none of our business. We appreciate all the good edits made by the “Anonymous Cowards” out there just as we do those made by everyone else. However, we do encourage everyone to use their own name, or at least a consistent alias, if possible.
There are some fairly obvious corollaries to be derived from the precept “get your own self out of the way” (with the specific implication “this is really not about you”).
We’ve had a bunch of people pass through who want to talk about e.g., their revolutionary approach to point-set topology, or how to use categorical ideas to develop a private theory of music, or deep insights into how categorical concepts shed light on the very structures of consciousness, or their ruminations on mathematical aesthetics, or their ideas on how gravitation should be understood in terms of electromagnetic effects.
In all such cases, we’ve had to tell them to go away and leave us alone. Not that we deem all such people to be crackpots; some may actually be fine thinkers. But we have other things we need to be doing.
People who have seen the description at nLab that this site is a “public place where people can make notes on stuff” may get the wrong idea. For example, students have sometimes set up shop and set about writing up stuff that is currently occupying them, without regard to what is going on in the rest of the nLab. They are usually told (politely) that they are misusing the nLab, and that such articles will unfortunately have to be removed.
A more accurate description, given at the article About, is that the nLab is perhaps best conceived as a group lab book, with the idea that we scribble things down that are of common interest to other researchers here. That’s closer, but it’s a bit simplistic. What makes the nLab somewhat different from a traditional group lab book are the numerous hyperlinks between the parts of the nLab, meaning that the scribblings should (eventually) be well integrated with what is taking place elsewhere. The integration works best when editors become somewhat aware of related articles and what has gone into them.
Of course newcomers are not expected to know everything about what related articles already exist on the nLab; the established contributors are generally quite happy to help make connections between new and old material. In return, however, newcomers are asked to be sensitive and receptive to this integrative process. You could think of the nLab as already an evolved organism, with limbs and extensions being constantly grafted on, but in a controlled way so that the organism does not reject the graft as being of the wrong type. In Piagetian terms, new material might either be easily assimilated into the existing structure; or, some extra arrangements might need to be made to accommodate it comfortably, a process that may require patience and good will between the participants.
Again, the nForum is the place where we openly discuss such matters.
There is plenty of scope for different forms of personal expression; there is not a single uniform style throughout the nLab. That being said, idiosyncrasies in style are much the secondary consideration; getting the goods out there in useful efficient form for the reader (including one’s self) is primary.
Unless you are supremely confident in your expository skills, the advice if you are a newcomer is generally to write straight mathematics (or physics, etc.), aiming for formal definitions and statements of results and the like. Not write imagined dialogues in the manner of Lakatos’s Proofs and Refutations, or long essays, or stud the discussion with abundant scholarly footnotes and other marginalia. Such devices have a tendency to clutter or distract or call undue attention to themselves. Anything that distracts or deflects the reader’s attention or any unnecessary digression is, in mathematical writing, generally bad.
Similarly, wordplay should be used very moderately, and the impulse to flaunt one’s broad knowledge and culture (in the manner of David Foster Wallace, say) should almost never be indulged. A little levity can be a fine thing, but again, the overriding principle to remember is that what we want most of all is to convey scientific insight, and this is best accomplished when the English is smooth and unobtrusive – doesn’t call attention to itself. You may be the greatest wit since Oscar Wilde, but your privately amusing puns and learned allusions may be getting in the way here, and actually your readers might resent you for it. Just try to be sensitive to that, please. If you want a place to display your erudition, start your own blog.
To avoid any misunderstanding: we are not suggesting that one should write the mathematics (physics, philosophy) in a stuffy or formal or bureaucratic way. To the contrary, it can often be effective to adopt a light conversational tone, taking the reader into your confidence as it were; on the nLab we are often more conversational than is the traditional style in published papers. But the expression should be an unaffected one (being too chummy is as bad as being too precious). Just remember the prime directive, and you should be fine.
All nLab editors are expected to use the “iTeX” mathematics typesetting language of the instiki software, which displays in web browsers using MathML/MathJax. If you know TeX or LaTeX, this should not be very difficult to adapt to; most mathematical typesetting commands will be the same. Some of the more important (though still fairly minor) differences are documented in the FAQ.
In the first place, to get started, writing a “stub” article (even just a sentence of two, just to get an idea down) is perfectly fine. Hopefully that will grow into something more polished, maybe with the input of others, but you shouldn’t worry – just make the stub intelligible enough for someone else to pick up the thread. Some people at this stage start a list of references to come back to, which can also be a good idea. If nothing else, a link to a relevant Wikipedia/Encyclopedia of Mathematics/MathWorld/SEP page — which should have some references of its own — can be the germ of a reference list.
Most nLab articles are titled by a concept (usually to be formally defined in the article). There are also pages titled by naming a result (e.g., Tychonoff theorem), sometimes in synopsized form (e.g., closed projection characterization of compactness). Some articles are titled by a person’s name, others by a book title (sometimes as referred to colloquially, e.g. Elephant). But nLab pages are not usually named with the sort of title you might see on a mathematics paper, such as “On a conjecture of Grothendieck”.
If you look at a typical nLab entry which has grown up a little, you will frequently find it organized along the following lines. First comes an Idea or Introduction section, usually with language similar to language you might use during a hike with a colleague on mathematics, with few to no symbols and giving the general idea without getting too technical. Then you might see a Definition(s) section which gives one or several precise definitions, followed by a Properties section or Basic Results section, an Examples section, a Related Concepts section, and a References section. By no means is this (Wikipedia-like) organization rigidly adhered to, but it is certainly common. At the top (if the author(s) of the page didn’t forget it), you will see a Table of Contents which serves as a broad outline of the contents (with sections, maybe some subsections, hopefully not too many sub-subsections – more subs than that and it can get ridiculous).
Inside each section, the material is often arranged by making effective use of environments (definition, theorem, lemma, remark, etc.). How these are used is a matter of personal discretion. The best advice is to aim for a happy medium, between one extreme of erecting great walls of text (which can look like a sermon being preached, and where the reader can get lost), and another where the material is so finely diced into atomic environment units that the reader is in for a bumpy ride. Ideally the material is arranged somewhere in the middle, allowing for a smooth narrative flow, and where the environments are not too cluttered but act as well-placed signposts. Visually the arrangement should look appealingly smooth. Display lines (as in TeX math display mode) can often aid in that, breaking up big chunks of text and allowing for emphases where appropriate – but too many of them and it backfires.
Choice of notation is largely up to the individual. It would be impossible to maintain a consistent choice of notation throughout the entirety of the nLab, because there are just too many authors and the nLab is too vast to keep track of it all. There is no Central Planning Committee for this type of thing. Thus, regarding notation, you should think of each article as a self-contained unit — but do please try to maintain notational consistency within each article.
This means especially: try to be respectful of the notation others have already introduced. If they use a calligraphic font while discussing a concept, then it will help the reader if you use the same font for the same concept later in the article, even if you don’t personally like calligraphic fonts that much. Above all: don’t take it upon yourself to just change all the notation to suit your own liking. If you feel strongly about notation – and many of us do – then you can plead and argue your case at the nForum for changes you want made (within reason of course – arguments shouldn’t be overly long). Hey, you may be right, and the rest of the community will listen. But if a consensus or compromise is not reached, then please find it within yourself to adapt to what was there. (When you start an article, you can introduce your preferred notation, and then you’ll be on the other side of that situation, right?)
For further words of wisdom about notation and sundry other expositional matters (many of which are being discussed without particular attribution in this article), please read Halmos; it is strongly recommend as a great and helpful article written by an unquestionably excellent expositor.
The format you will see in a typical nLab article is somewhere between a Wikipedia article you might see on a topic in mathematics or mathematical physics, and an academic article in one of those areas. The organizational outline seen in the table of contents is very Wikipedia-like, but unlike Wikipedia, the development may be like that of an academic article with formal definition environments, theorem environments, etc., and with point of view that is not neutral with regard to where we tend to place emphasis: the nPOV and string theory. We also may conduct some original research, quite unlike Wikipedia.
But in most respects, there should not be too many surprises for people familiar with both types of articles. For example, under a References section we follow a standard type of bibliographic format (author(s), title in italics, journal with volume and number or publisher, date, page numbers), linking to online material wherever possible (always legally!!). In the text where one wants to refer (and link) to a bibliographic item, there is no official format for this, but the tendency is to use something simple like author-name-date in brackets, rather than putting a number in brackets. The page HowTo gives detailed instructions on how to do this.
Occasionally there is redundancy or repetition in the nLab; to a degree this is tolerated (a definition or proof may be recalled). However, we don’t want too much of that. If you set out to create a new page, you may be told when you announce it at the nForum that we have that on some other page with a different title. Don’t be discouraged: the material will of course not be an exact duplicate and there will surely be things which can be usefully incorporated into the extant article.
But: in that situation there may have to be a “redirect”, where the term you used to title your article should now be a term which redirects to the extant article (or, it could go in the other direction, but usually not), and then the newly created article, after relevant material has been incorporated, is made “history”. Please see HowTo for detailed instructions on how to perform this action. It’s a slightly fiddly procedure though, and usually a more experienced editor will be happy to do it if needed.
Specifically, there are some features enabled by the software, but which are somewhat deprecated or downplayed at this point in time in nLab culture.
One such feature is the “query box”. This was once used so that someone reading an nLab article could insert a question or even have a running sequence of comments embedded right there within the article. But we found this didn’t really work well, one reason being there it didn’t notify author(s) that a question was being asked, so that you’d see the query only if you chanced to go back to the article. Some queries might sit for years before being noticed! And we’re still trying to clean up query boxes.
So please don’t use this the query box feature – we ask that you ask your question or post your comment directly at the nForum. If you see an ancient query box, you or someone else should shunt it over to the nForum which serves an an archive as well.
Another thing we want to downplay (more recently) is the use of the footnote feature. It’s really not a footnote at all; functionally it’s more of an endnote that gets plopped slightly awkwardly at the bottom of the page in the same sized font as anything else, but without any html heading that announces: Footnotes. The bottom line is that it doesn’t look very good and calls ungainly attention to itself, something that a footnote is not supposed to do.
Instead, if it’s about something minor, consider using a link to another part of the nLab (or wherever) where the point is discussed. If it’s less than minor, then maybe consider placing the remark in a Remark environment there in the text. In case of doubt, ask for advice at the nForum.
This is perhaps the touchiest aspect of these recommendations, so we will say it as plainly as possible. The bottom line is this: the nLab can only function in an atmosphere of mutual consideration and respect; it will never work if there are overhanging attitudes of “my way or the highway”. Somehow it has been at least moderately successful, we feel, despite the fact that there are already at least a few strong-willed personalities involved.
Perhaps the main reason it has worked is a prevailing ethos of cooperation, and in particular an unspoken obeisance to a “prime directive” (repeating ourselves somewhat):
Try to arrange nLab material so as to maximize scientific insight, letting the power of the nPOV shine through, in smooth and unobtrusive language. Try to get your own self and personal idiosyncrasies out of the way of this happening.
The typical underlying tensions between
not wishing to step on the toes of others who have put some work into the nLab, and
wanting nevertheless to revise the nLab to make it better
are seemingly resolved by correctly interpreting and implementing that directive, through controlled discussion at the nForum. Of course, helping matters along is a semi-cohesive philosophy at the core of our (otherwise loosely connected) working group, of the importance of category theory and higher category theory to organize and simplify mathematics (and physics and in some respects philosophy). Those who do not share in that vision (or mission, whatever you wish to call it) might not be so easily assimilated into the nLab group – although we are open to possibilities – since such people may have very different ideas of what to emphasize in mathematics.
An example where a nontrivial rewriting of an article is welcome is where it makes the underlying principles clearer and the development more economical, or where it lays bare unifications with other subject areas, etc. In other words, where the actual mathematics is improved (from the nPOV). Sometimes entire articles may be revamped for such reasons.
Examples where rewrites are maybe not so welcome is where it comes to differences in style between otherwise reasonably competent writers. One writer may prefer a slightly more conversational tone (using 2nd person), and another a slightly more formal tone (using 3rd person). If one feels an impulse to change something in the style of another, the first question that should be asked is: is this really going to materially improve the reader’s reception? Sometimes it might, oftentimes not really. But this is felt to be an important enough matter to make a revision, it should be discussed beforehand at the nForum – don’t shoot first and ask questions later. In all other cases, it’s probably better to let it go. Concentrate on the mathematics.
Another small example which may be worth addressing: discrepancies between American and British (Commonwealth) spellings. One might see different spellings of the same word in the same article! Should alternate spellings (which are correct according to the author’s dictionary) within the article be aligned to make them consistent? The nLab way seems to be to respect each other’s differences in this (minor) respect: if one person writes ‘neighborhood’ and another ‘neighbourhood’, then that’s okay: let it go. Similarly, we don’t try to enforce consistent standards of punctuation and formatting, where conventions also vary regionally: e.g. do quotations use single or double quotes, does punctuation go inside or outside the quotation marks, is an apostrophe written as don't or don\'t, etc. This extends also to respecting each other’s choice of whether to use : or \colon in mathematical notation.
Unlike the above advice about notation, such variations in spelling and punctuation may occur even within a single nLab page, and there is no need to try to make them uniform. Think of it as a token of respect we have for one another: we may come from all corners of the earth, but we come together to build the nLab. We can tolerate a small difference in cultural background such as this. (It was, however, agreed informally long ago to use American English spellings in page titles, although of course other spellings should be included as redirects.)
Last revised on July 21, 2022 at 19:36:27. See the history of this page for a list of all contributions to it.