Tricki
a repository of mathematical know-how

Guidelines for writing Tricki articles

Introduction

There are two different (but potentially overlapping) classes of Tricki article: core articles and navigation pages. A core article is an article about a specific mathematical technique, or cluster of closely related techniques. A navigation page will typically consist of a few annotated links to pages that will either be core articles or more specific navigation pages. An example of a core article is this one on the tensor power trick. An example of a navigation page is this page on proving equalities and identities. Since the guidelines for these different types of articles are somewhat different, we shall discuss them separately.

These guidelines concern the style and format of an article. For suggestions about the content, see the page on what a Tricki article is allowed to be about. For advice about how to upload an article that you are ready to write, see the page on how to create a Tricki article. For information on how to use the Tricki's markup to structure articles, see the page about sectioning.

Core articles

There is a recommended format for core Tricki articles that you are strongly urged to adhere to. It is intended to be just tight enough to give the Tricki a uniform feel to it, but no tighter. The recommendation is simply that articles about a technique should illustrate that technique with a reasonable number of examples, and that the appropriate sectioning tags should be used to show very clearly which parts of the article are giving examples and which are general discussion. If you browse the Tricki, you will see how this works.

As for the style, we recommend that it should be chatty, and no more formal than is necessary to explain a technique. Imagine that you are trying to explain a technique in person to somebody who doesn't know it. What you are not doing is writing a textbook in theorem/proof/definition style. If you feel the need to use this style in parts of your article, make sure that it is counterbalanced by a great deal of accompanying discussion.

If you want to use a term that you expect most, but not all, of your readers to know, then you have at least three options. One is just to go ahead and define it anyway. Another is to define it but hide it using the Tricki's hidden text feature, to make it less distracting for those who want to skip it. See the Tricki formatting page to learn how to do this. A third option is to put in a link to a Wikipedia article about the term in question. (We fully expect the Tricki to be parasitic on Wikipedia in this way, and have made it easy to add such links.)

The purpose of a navigation page is to take a Tricki user closer to an article that is likely be helpful for dealing with a particular mathematical problem. These pages have a hierarchical structure that may have many levels. For example, the page different kinds of Tricki article has a link to a page for general problem-solving tips, which has a link to a page called mathematicians need to be metamathematicians, which has a link to a page about which techniques lead to which kinds of bounds, which has a link to a core article about extra logarithmic factors.

The recommended format for a basic navigation page is that it should start with a brief explanation of the purpose of the page, and should follow this with a list of annotated links. The annotations should be hidden, so that as many as possible of the links are visible at the same time. The navigation page on proving equalities and identities, mentioned earlier, shows how this can be done.

Some navigation pages may be less basic and will include a significant amount of accompanying explanation. The recommendation for these is that the links should be easily accessible at the top of the page, if at all possible, and the general discussion should come later. See for example the extremal combinatorics front page. The reason for this recommendation is that we want it to be possible to use navigation pages for quick navigation through the Tricki as well as slow considered exploration. Too much scrolling down to find appropriate links will make the Tricki much less convenient to use.

Any Tricki page that comes immediately below a navigation page should contain a link back to it under the heading "Parent article". This will make it quick and easy for Tricki users to retrace their steps. Of course, that could be done with the back button, but it will also make it quick and easy to go up a level of generality.

The title of your article

The primary purpose of the Tricki is to tell people how to do mathematics, and it is good if titles of articles reflect this. Especially good are titles that take the form of commands, such as Clarify your problem by making it more abstract. It does not matter if the command is one that applies only part of the time: the articles are vying for your attention, but it is up to you to decide which commands you will obey. Also good are titles that summarize in one brief sentence the main message of the article, such as Mathematicians need to be metamathematicians. Some articles are of a special type and have titles that make this clear, such as Algebra front page or How to use ultrafilters. The sort of title to avoid if possible is "Applications of the Jordan-Hölder theorem": a reader who has not heard of the Jordan-Hölder theorem will have no idea what the article is about.

The length of Tricki articles

As a rule, Tricki articles should be long enough to be satisfying, but short enough that they can be fully digested. A recommendation for core articles is that they should be focused on one technique only. There may sometimes be a temptation to discuss different techniques in a single article; for instance, they might be used to solve similar problems. In such a case, if the techniques do not deserve articles to themselves, then it may be reasonable to merge them into a single article. However, if each one takes a long time to explain and can be illustrated with several examples, then it is probably better to write a navigation page about the class of problems they are useful for, with links to separate articles about the techniques.

A navigation page will not be convenient to use if one has to search through a very long list of links. When a navigation page seems to be becoming too long, we recommend breaking it up by classifying the links into categories and having separate navigation pages for each category, with a higher-level navigation page with links to these newly split up pages. It is not necessary for the categories to be disjoint. An example of a navigation page that will probably have to be split up soon is How to use mathematical concepts and statements, which could perhaps be split up according to the broad area of mathematics that a particular concept or statement is particularly relevant to.

Don't let your article disappear

Of vital importance to the Tricki is that articles, once written, should be discovered easily by those who are likely to benefit from them. If you are contributing an article, then you should take this at least as seriously as the content of the article. One obvious method of integrating your article into the Tricki is to add a link to it from an appropriate navigation page, or to create an appropriate navigation page if it doesn't yet exist. There is also a system of tags: see How do I make my article show up in searches? for more details.

Incomplete articles are welcome

Suppose that you want to write an article but feel that following the recommendations on this page is too much effort. Then consider writing an article that is incomplete. For example, you might have a technique to describe, but be unable to think of more than one good example to illustrate it. Or perhaps you have some examples but cannot think of a good way of explaining how to recognise situations where the technique can be used. If you go ahead and write the article anyway, then put in a prominent place a sentence such as "This article needs more examples", explaining how you would like to see the article developed.

Similarly, if for some reason you can't face thinking about how to make your article easily accessible, don't let that put you off writing it: it is better to have a hard-to-find article than no article at all, and others can always add tags, links, and navigation pages if you don't. Again, if you decide to leave the task to others, then include in a prominent place in your article a sentence such as "There is no suitable navigation page that I can link from to this article: somebody needs to write one."

A more drastic kind of incomplete article is a navigation page that is full of links to nonexistent articles. We expect there to be many of these in the early stages of development of the Tricki: they will constitute a sort of wish list. Such articles are encouraged, since they may well prompt others to write the missing articles, they will provide a ready-made structure into which many new articles will fit, they will give shape and direction to the Tricki right from the start, and they will encourage people to reflect on how best to organize the material that the Tricki will eventually contain.

Style

When linking to other pages, it is recommended that you avoid using non-descriptive link-text. For example, instead of writing 'See this page', write 'See the page on guidelines for writing Tricki articles'. When possible, one should aim for what is written to make complete sense even if the article were to be printed.

What is a Tricki article allowed to be about?

How to create a Tricki article

Formatting: structuring an article

How do I make my article show up in searches?