Style guide for questions and answers

Question

Following the style guides on Stack Overflow and Wikipedia, I would like to propose that we create a style guide of our own. Let's hold ourselves to a high standard and create or promote questions and responses that can be understood and followed by people who have just started with Ubuntu. Let's make this a hallmark of the Ubuntu Stack Exchange over other resources.

In what ways do people overcomplicate responses to questions? What can they do to ensure that their responses are understood by all audiences, not just the most technical among us?

What would a badly formatted question or answer look like compared to a well formatted variant?

Should we avoid simply forwarding people to wiki and help pages, and provide a response tailored to their individual question? Or is there a way that an external resource can be incorporated into a response without completely deferring responsibility to it?

Answer 1

It appears that most of the questions will be of the form "How do I do [some action]?" I think the perfect answer to one of these questions would be a brief walkthrough of the steps required to complete the action.

If the question is something new users might have to deal with, put the GUI answer first, ideally with a screenshot.

Guidelines

• Break up your text, leave room to breathe.

  A wall of text can look tedious and some people just won't read it. Break up your text into small paragraphs of a few sentences. Point out where the important information is.

• For commands that users need to type into their terminal use backticks so that the site renders it in a monospace font so it's easier to distinguish what is a command and what is part of the surrounding text.

• Don't use $'s for answers in the terminal (unless you're also showing output).

• If something is a series of steps, break it down into a numbered list so it's easier to read instead of one line.

• Don't overformat your questions and answers, they become hard to read, remember that less is more, not more.

• Question titles should ideally be actual questions, beginning with a capital letter and ending with a question mark.

  • Good example:

    How can I upgrade to Ubuntu 12.10?

  • Bad example:

    upgrade ubuntu 12.10

  You should not force the title to be a question, but at least try to write a meaningful title.

Images

• If an image is too large to fit on the page, instead of reminding the user that they can right click it and select show image, make it a link to a larger version of the same image. Don't use pre-formatted linking thumbnails with extraneous information in them.

• Images and screen shots should be on their own paragraph; Make sure the image referece in the Markdown has a blank like before and after it. If you annotate an image, you can use <br>*Picture of a cat* on the same line to stick the text right onto the image. Use this technique sparingly.

• Images should not be used if the sole purpose of the image is to display text (terminal or otherwise). An image takes more bandwidth and is does not support screen reading software. Text should instead be copied into a quote or code block as appropriate.

Links and References

• If your answer is behind a link, on someone's website or in a manual somewhere, rather than just linking to it, summarise the information in your answer. Make sure that your summary is a good representation of the linked content, since the link might not be reachable in the future.

  • Good Example:

    The Ubuntu Wiki has a solution for your problem:

    • Go to the Ubuntu One Preferences ...

      [...]

  • Bad Example:

    Here's your solution: http://dead-link.example.net/

Also remember that blogs and news sites quickly go out of date, punting someone to an older blog means we can't improve it over time like we can an answer right on the site.

• Give credit where credit's due

  You are more than welcome to post an answer based on someone else's findings. Just give them the credit they deserve. Do not paraphrase someone else's text, but quote it directly.

  • Good Example:

    It says that was "Suggested in xulrunner-1.9.1 in Ubuntu Karmic package "xulrunner-1.9.1" by ZhongHan Cai on 2009-09-21". There, it says that it was "Suggested in evince in Ubuntu Natty package "evince" – via K. Deniz Ogut

  • When you make any changes to a quote, mark them as such by putting the word or sentence in square brackets. If you emphasise specific parts of it, make your change apparent:

    What [does] a badly formatted question or answer look like [...]? – via Evan (my emphasis)

Examples

Good formatting

1. Do step 1 (command -1)
2. Do step 2 (command -2)

Bad formatting

First, do step 1, then do step 2.