The Style Guide for the Knowledge base
All new articles are to be written in English. This does not mean that we believe the content should only be available in English. We would like the content to be available in as many languages as possible. However, so that we can verify the accuracy of a new article, it first needs to be written in English, preferably in U.S. English.
As long as the content is accurate, don't be afraid of poor English or not understanding all of the markup conventions—someone else will correct what you write. You creativity and expertise is what's important. Write text, though, that is not overly complex and might not be understandable by second-language English readers.
Titles & Meta Text
The titles of articles and categories should be succinct and not a phrase or sentence. Unless you're creating an FAQ, a title should not be in the form of a question. Titles for categories and articles at every level should be written in title case.
Each category and article should have an Excerpt. When creating or editing an article, you'll see a box for entering an excerpt. This is meant to be a brief description of the article that is visible on the parent, category page. An excerpt should be a short sentence or a fragment of a sentence. It should be written in title case and end with a period. Never use exclamation points in titles or excerpts. Excerpts should fit in their entirety on the category page listing and not be cut off by ellipses.
References & Links
Category pages which contain links to many other documents should be grouped into sub-categories that are embedded into the main document. Sub-categories should be listed below articles linked directly on the category page.
Formatting and Highlighting
All SQL statements and functions that are referenced, should be linked to their respective page of the documentation. Functions that are referenced should be typed with a space between the parentheses.
Reserve words should always been typed in all capital letters, while the names of databases, tables, and columns should be in all lower-case letters.
See Editing Help for more help with formatting.
Content & Word Usage
Never use exclamation points and try to avoid using question marks in the content of articles.
Examples
Embed code samples in the appropriate macro, such as the code macro or the sql macro.
When showing examples involving SQL statements, don't include the leading prompts (e.g., MariaDB [test]> or ->). This will make the results easier to read and easier for readers to copy and paste the content to their computer.
Capitalize all reserver words within an example, including smaller words (e.g., AS, AND). Don't try to highlight or italicize any of the text—nor add comments in-line, within examples. Instead, describe the example before or after it. All examples should be explained. Don't assume the reader understands the key information contained within the example.
Try to avoid examples that are so wide that the reader has to use the horizontal scroll-bar. Instead, break the code or SQL statements, as well as error messages into multiple lines. When doing so for command-line examples, add the \ that you would use in a shell. If appropriate, say in the text that follows the example that you have adjusted the results for better formatting. For results tables that are too wide but are for only one row, try using the \G delimiter to getting narrower results.
