74

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?

0

1 Answer 1

62

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.

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.

5
  • 1
    "[. . .] punting someone to an older blog means we can't improve it over time like we can an answer right on the site." Did you mean pointing, or is there a pun here?
    – 000
    Nov 25, 2012 at 21:04
  • I am glad you still included a comprehensive discussion of responses using the command line rather than focus on just the GUI which is where I imagined this question and answers were headed after the OP mentioned "responses are understood by all audiences, not just the most technical among us". There remains a big role for the command line in Ubuntu and I regard that as a good thing, hence my +1.
    – haziz
    Dec 14, 2013 at 19:44
  • How do you make buttons like ctrl + alt + T? I never found that in the styling guides.
    – James
    Sep 13, 2016 at 2:27
  • What of titles? "Use the Capitalized Form" or "Use the sentence form"? Feb 16, 2017 at 9:36
  • @James, you need to use <kbd> HTML tags for that Nov 17, 2017 at 20:55

You must log in to answer this question.

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