15
$\begingroup$

Editing posts is a basic feature of Stack Exchange: everybody can edit everything (edits may be audited if you have low reputation). Since our site lives and dies with the amount and ratio of useful, accessible content, it is important that as many people as possible pitch in and help making posts better.

This contains individually linkable guide on

$\endgroup$
12
$\begingroup$

Titles

Titles are important: they represent the question on the main site, in search results and in RSS feeds. We want users to visit questions (and to answer them) and a good title may make just the difference.

Also, titles fuel the search for related questions in the "Ask Question" form. A question titled "How to analyse this piece of code?" will never stand out as containing my answer; "What is the runtime of this nested for-loop?" just might.

Titles are tough. They have to be expressive enough to tell readers what to expect but short enough to be read at all. Here are some guidelines towards writing better titles.

  • Level of detail

    There needs to be enough of your question in the title so that users should know what to expect. If they are surprised at what they find after clicking through, the title was bad. On the other hand, don't try to put every detail in the title; that's what the main post is there for.

    "Improve shortest-path algorithm" is too generic, "How can I save $\Theta(n)$ memory while computing shortest paths on ERM-graphs with the variant of Dijkstra given in "Some book title" by S. Author?" is too detailed. A good title would be "Can Dijkstra use less memory on random graphs?".

    Rule of thumb: Accurately describe your core problem. Don't be overly generic, but also not too detailed.

  • As short as possible and as long as necessary

    The title needs to contain a snappy version of the question, but not a lot of information; that's what the main post is for.

    Rule of thumb: Less than half a line is probably too little, more than one line is probably too much.

  • Choice of words

    A good title uses computer science jargon where appropriate. Use "shortest path" instead of "quickest route" and "is Turing-complete" instead of "can compute everything".

    Don't overdo it, though; if a term has been defined in a paper published three weeks ago, it will not be recognised.

    Rule of thumb: Use terms a CS undergrad student would know and use.

  • LaTeX

    It is tempting to title your question "Is $\{ a^k b^{2k} c^m \mid k,m \in \mathbb{N} \} \in \mathrm{CFL}$?" but that is bad for two reasons: mathematics is hard to search and titles are not rendered by MathJax everywhere, e.g. in RSS readers. Use "Is this language similar to $a^n b^n$ context-free?"

    Note that there is also the possibility of using Unicode, at least for "flat" formulae. For instance, instead of

    Is $\Theta(f) = \Omega(f) \cup O(f)$?
    

    Is $\Theta(f) = \Omega(f) \cup O(f)$?

    you could use

    Is Θ(f) = Ω(f) ∪ O(f)?
    

    Is Θ(f) = Ω(f) ∪ O(f)?

    which you can copy & paste from the rendered output. Make sure to insert some spaces, though.

    Combining both forms can be a suitable compromise:

     Is $Θ(f) = Ω(f) ∪ O(f)$?
    

    Is $Θ(f) = Ω(f) ∪ O(f)$?

    Rule of thumb: Use as little formulae in titles as possible. Never use more than can be read comfortably without MathJax.

Keep one general guideline in mind: if you have trouble coming up with a good title, you are not ready to post the question yet, or it may be unsuited for the site at all.

$\endgroup$
  • 1
    $\begingroup$ To be clear, this is my personal view and the way I (try to) edit today. If you disagree, these items are open for discussion. $\endgroup$ – Raphael Jan 27 '14 at 9:03
8
$\begingroup$

Tagging

Tagging is an important feature of Stack Exchange for several reasons.

  • Tags help searching.
  • Tags are used to select "Related" questions for the site bar.
  • Tags help disambiguate titles in question lists.
  • Tags allow users to filter what they see.

The last point is probably the most relevant: experts of an area may not even see a question just because it is badly tagged.

Unfortunately, new users almost always tag their questions badly because they don't know the right keywords and/or are not familiar with the tag space or the platform. We have to help them out.

Everyone who can edit posts can edit tags, too. Here are some guidelines as to what represents good tagging.

  • Category tags

    This is not a feature of the platform, but we have some broad tags that describe roughly where in CS the question lies. Examples are , , and .

    Rule of thumb: Every question should have at least one category (or at least frequent) tag.

  • Classification tags

    Once you established the broad category, go into detail. Is your question about or or both? Are the at hand or ?

    Rule of thumb: Every question should have at least two more specific tags.

  • New tags

    Don't be afraid to create new tags. If they end up being not useful, that is no other questions are tagged similarly, the system will automatically delete the tag.

    If, on the other hand, you create an undesired tag or a duplicate, we can delete tags and/or create synonyms so future visitors are more likely to find the appropriate tags.

    Rule of thumb: create new tags if you think they may be useful for tagging more questions.

    Note: If you think older questions should get the new tag (maybe a once specific enough tag needs more specialisation as more questions appear), please raise the issue here on Meta; retagging lots of questions is an invasive step that should not be taken without discussion.

$\endgroup$
  • 1
    $\begingroup$ To be clear, this is my personal view and the way I (try to) edit today. If you disagree, these items are open for discussion. $\endgroup$ – Raphael Jan 27 '14 at 9:03
5
$\begingroup$

Formatting

Markdown

Use the basic formatting provided by Markdown to structure posts: lists should be Markdown lists (nesting works!), links should use the [text](URL) syntax, emphasis should be placed by *...*, citations put in > ... paragraphs and source code in code blocks (prepend lines with four spaces). There is extensive documentation of what is possible; use it wisely.

Rule of thumb: Edit for clarity. Prettify links and introduce structure. Remove long emphases (and almost all bolding).

LaTeX

When mathematics are involved, the best option is typically (not always) to use LaTeX. New users often don't know that we have MathJax and use code environments or something else to typeset their formulae. In these cases, we should help them along by translating their mathematics to LaTeX (and post a comment so they know). See also this quick guide.

Existing LaTeX may have to be fixed to use standard notation or just to improve readability. Examples are to use \mid instead of | in grammars and sets, set longer formulae apart (and maybe \displaystyle them) or using align-environments for alignment.

It is not necessary to edit away Unicode maths as long as notation is consistent.

Rule of thumb: Edit mathematics for clarity.

Images

Images are often a good way of illustrating a point. However, images should be

  • accompanied by credit to the source (if applicable),
  • not be overly large and
  • easy to "read".

Every editor can e.g. trim away the desk in a photograph of a graph drawn on paper (just reupload the trimmed version). If you are particularly motivated (and want to improve your TikZ skills) you can recreate photos, but that's not to be expected.

In many cases, the only think to do (in appropriate time) is to comment and ask the user to make the changes themselves, especially regarding credit.

One thing to shoot down without mercy are screenshots of problems: everything that is text should be copied in the question (or answer) text so that it can be searched, edited and screen-read.

Rule of thumb: Fix what you can and delegate the rest to the user. Flag if the problems are significant (e.g. question consists only of images).

$\endgroup$
  • 1
    $\begingroup$ What would the stance be on editing a post to add a link to a relevant resource? I got the impression from you a month ago that they were okay, but I was under the impression that an edit like that might be too minor. $\endgroup$ – Dennis Meng Feb 8 '14 at 6:02
  • 1
    $\begingroup$ @DennisMeng: Depends, I guess. Is the resource critical to getting the point across and/or obligatory (material is taken from it)? Definitely edit. Is it just third example? Probably not; add a comment. In between, there's a gray area. $\endgroup$ – Raphael Feb 8 '14 at 14:19
4
$\begingroup$

Gutter

Anything along the lines of

  • "Hi everybody",
  • "I'm only a beginner but I'm really, really hard-working" or
  • "Thanks in advance, cheers"

should be done away with immediately. While we can appreciate nice tone, questions and answers are not supposed to be (part of) a conversation.

Other elements that can be removed are

  • things like "EDIT:"
    We keep a version history; every post should be "whole" at any time. Exceptions can be made if, say, a mistake has enough illustrative value to be kept.
  • huge chunks of program code (ask for pseudocode) and
  • redundant examples (common for challenge problems).
$\endgroup$
4
$\begingroup$

References

Rule of thumb: Provide references so that the work is uniquely identified and easily accessible for readers (in case of online resources).

Academic resources

References to books or papers should consist of more than a link or a book name. Not only do links break eventually, they also require a click; the reference should be clear as is. This means that title, authors and year should be stated. If available, a link to an online version is great; use DOI if at all possible (such links survive moving resources).

Google Scholar is a great help for finding meta data and free copies of articles.

As for formatting, I like to use a style emulating articles:

I got this from CLRS [1] but Sedgewick's work [2] seems relevant.

---

  1. [Introduction to Algorithms](http://mitpress.mit.edu/books/introduction-algorithms) by T. H. Cormen et al (2009, 3rd ed)
  2. [Implementing Quicksort programs](http://dx.doi.org/10.1145/359619.359631) by R. Sedgewick (1978)

I got this from CLRS [1] but Sedgewick's work [2] seems relevant.


  1. Introduction to Algorithms by T. H. Cormen et al (2009, 3rd ed)
  2. Implementing Quicksort programs by R. Sedgewick (1978)

Remember that the official versions of articles are often paywalled (you may not notice if you surf from a university IP); if you know a preprint version, please provide a link to it as well (not only!). Please don't link knowingly to illegal resources, though.

For books, you should include at least title and authors (year published and edition would be helpful). For papers, you generally should include at least title, authors, and where it was published (e.g., conference name and year; or journal name, volume, and number).

Online resources

Cite with author, URL (prefer permalinks) and date of last access. You can use above scheme, or go inline like this:

[some article](http://hipblogginsite.com/hero/hype-topic-explained) by John Doe (accessed Jan 28, 2016)

Since websites usually go away (linking schemes break, domains change, sites are shut down, ...) and contents can change without notice (Wikipedia edits), make sure to quote the essential parts. Nobody wants to read dozens of pages in order to follow your post, so that's a good idea in any case.

If the website offers revisions (e.g. Wikipedia) you may want to link to the exact revision you are referencing. This is essential if you are asking about unclarities or suspected mistakes in the material, which will hopefully be fixed in the future and thus leave your question meaningless (unless you included the relevant passage as a quote, in which case a link to the revision is still a good idea).

$\endgroup$
  • 1
    $\begingroup$ Why is it not enough to only link a preprint? $\endgroup$ – Discrete lizard Feb 25 '17 at 11:06
  • 1
    $\begingroup$ @Discretelizard Because it's not the "official" citation. In science, you always cite the "best-published" version (journal > conference > thesis > preprint). Linking preprints in addition is encouraged here. $\endgroup$ – Raphael Feb 25 '17 at 19:19
3
$\begingroup$

Language

Language often is a matter of taste and many of us are non-natives. Therefore, we are bound to find "strange" language more often than not, but that is no reason to edit everything.

On the other hand, posts need to be comprehensible. Sometimes, bad translations, inventive grammar and peculiar terms stand in the way of understanding a post.

  • Edit titles to be clear and correct. Titles are the business cards of questions and we want those to shine.
  • Edit posts only to a level of easy understanding.
  • Edit posts that use acronyms to introduce the long forms, too. For example,

    By performing BFS on the NFA we can find whether it accepts any word. Does DFS work, too?

    should become

    By performing breadth-first search (BFS) on the finite automaton (NFA) we can find whether it accepts any word. Does depth-first search (DFS) work, too?

    The acronyms can be dropped if they are not needed in the rest of the post.

    This does not only improve readability for non-experts (many acronyms are heavily overloaded across fields!) but also makes content easier to search for.

  • Never edit for style.

Use good judgement! Help users that try their best. If somebody clearly spent less time on writing their post than you reading it, just downvote or close vote (if it is not comprehensible).

$\endgroup$
  • 1
    $\begingroup$ Overall, this looks like reasonable advice, but I'm confused on some of the specifics "Do not"s. Why not edit for style? Why not edit to improve strange language? Is there a justification for that? $\endgroup$ – D.W. Jan 27 '14 at 5:12
  • 1
    $\begingroup$ @D.W.: I was rebuked a couple of times by users that felt style was theirs to decide. I figured they had a point. (People like to feel like they own their posts even if, in the strictest sense of the rules, they don't.) $\endgroup$ – Raphael Jan 27 '14 at 9:02
  • 1
    $\begingroup$ Ahh, OK, got it. Thank you for the explanation! $\endgroup$ – D.W. Jan 27 '14 at 16:40

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .