5

Every now and then I will stumble across questions and answers that have some weird formatting in the text after having been revised. Or they will have been reasonably formatted text bodies before, but somebody in the community will have imposed his understanding of formatting to the text bodies.

I have no personal objection with individual formatting when the initial questions are being asked or when answers are being given. Each to their own. My questions are about revising questions and answers.

General Question

Should we agree on some form of common formatting standards (not rules; too hard) regarding the formatting of questions and answers on DBA.SE when revising them?

Question Titles

For me issues about formatting sometimes arise when looking at the question's title itself. In some cases the title will be a simple copy of an error message just pasted in to the title box, in other cases it will be a title containing "all lower case letters" or a title with "First capital letter only".

General Title Formatting

The following question was asked on the English Language & Usage Stackexchange site regarding capitalisation of titles:

Which words in a title should be capitalized?

The answer from the above question and various other sources can be found here :

Hint:
The title for the above question itself should be correctly written as:

Which Words in a Title Should Be Capitalized?

Content of Question Titles

Titles should convey meaning to the readers and are the starting point for the community. In my opinion, they shouldn't be just a simple copy of an error message.

Error message title:

unable to start psql : no pg_hba.conf entry for host “::1” , user “postgres”, database “postgres”, SSL off

Wouldn't the following title be more acceptable (different title,same question):

Unable to Start PostgreSQL Instance Due to Error: No pg_hba.conf entry for host

Questions Regarding: Question Titles

  • Should error messages be removed/reworded in question titles?
  • Should question titles be revised according to capitalisation rules or should they be just left as is?

Similar Questions Already Asked

The above questions and musings regarding question titles have also been asked in the following StackExchange META communities:

Text Body (Questions & Answers)

Increasing the readability is probably the main reason for the community to revise a question and/or answer in the first place. This is also the initial reason why I am asking this question on meta.

Capitalization (US)/Capitalisation (UK)

I'll stick with the UK definitions for now

Capitalising the personal pronoun "I" is the first thing I'll do when revising a question or answer. Sentences that don't begin with a capital letter will also be corrected. Apart from those two obvious cases the only other reason to correct capitalisation is when removing it from certain words.

Product Names / Product Features

I have issues with product names shortened to postgres (is a user), mysql (is the shell for MySQL), sqlserver (could be the process name) and oracle.

I will normally correct these to their correct product names: PostgreSQL, MySQL, (Microsoft) SQL Server and Oracle (RDBMS) depending on the context. I equally advocate the use of the correct product feature names (e.g. Availability Groups vs. AGs) at least in once place in the post (presumably towards the beginning).

I believe that the community as a whole should uphold the correct spelling of the products, brands and features.

Quoting Text

When to quote and when not to quote?

I like the idea of quoting ...

  • to emphasise a previous comment (even from a different answer or the question itself)
  • to add a disclaimer
  • to add a note which I would like to point out something specific (possible abuse my side)
  • to add code output

However, when revising a question/answer I will refrain from adding quotes, unless some portions of the question or answer have obviously been retrieved from the question, a different answer or from a different web source (in which case I might even add the source link). In some cases I have code quoted output, because I find it more readable.

I personally don't like:

unable to start psql : no pg_hba.conf entry for host “::1” , user “postgres”, database “postgres”, SSL off

But I do like:

unable to start psql : no pg_hba.conf entry for host “::1” , 
user “postgres”, database “postgres”, SSL off

Code Text

Sometimes formatting code (especially long SQL statements) when revising a text body is the most tedious task. Should I leave the SQL statement to be scrollable beyond the boundaries of the formatted question or should I break it and pre-format it with an available tool?

If the code involves bash prompts beginning with # signs, there will be a lovely title in the text body which is totally unexpected. In other cases code that begins with ------ will be converted to horizontal lines separating the code.

Sometimes elements of the code will be specified in individual sentences to explain a topic or issue in depth. Should these code elements be formatted as code to relate to the code block or should they be just left as is?

When it comes to Product Names, Vendor Names, Product Features or other non-code elements I tend to cringe when finding these in revisions and will reset them if not too much fuss.

I guess a lot of editors/moderators have come across code issues in text bodies and have formatted them according to their best of knowledge.

Questions Regarding: Text Body (Questions & Answers)

  • Should product names / product features be edited to their correct spelling?
  • Should code formatting be limited to actual code blocks and/or code element to increase readability?
  • What are your thoughts on quoted text?
  • What are your thoughts on capitalisation?

Similar Questions Already Asked

haven't found similar questions yet

8
  • 2
    I suppose this could be split into a dozen of separate good questions?
    – Erwin Brandstetter
    Feb 2, 2018 at 16:30
  • 2
    You bring up a set of very good points, although, by the nature of its subject itself, the post seems kind of broad. I agree that splitting it would be useful.
    – MDCCL
    Feb 2, 2018 at 17:46
  • I’ll contemplate that. Thanks.
    – John K. N.
    Feb 2, 2018 at 19:41
  • 1
    Unrelated, but: "unable to start psql" is something very different from "unable to start PostgreSQL instance". And Postgres is an acceptable alternative name for PostgreSQL: wiki.postgresql.org/wiki/Identity_Guidelines
    – user1822
    Feb 3, 2018 at 14:52
  • @hot2use: the process name of the server process would be postgres
    – user1822
    Feb 12, 2018 at 7:47
  • @a_horse_with_no_name yes, you're right. Sorry, I'm writing with a foggy brain and a stuffed nose. psqlis the CLI and postgres with the various subprocesses (checkpointer process, writer process, wal writer process, autovacuum launcher process, and stats collector process) is the PostgreSQL database server process.
    – John K. N.
    Feb 12, 2018 at 8:09
  • I'm thinking of splitting my question into various Style Guide: .... questions and posting them here on meta, because my initial question seems to be too broad. What do you think?
    – John K. N.
    Feb 12, 2018 at 8:11
  • @hot2use I'm a little late to the response game but YES, individual ones to be voted on by the community are good. One mega question is better as links to the individual smaller questions.
    – jcolebrand Mod
    Mar 6, 2018 at 18:19

0

Reset to default

Browse other questions tagged .