The Style Guide for the Knowledge Base

You are viewing an old version of this article. View the current version here.

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 conventionssomeone else will correct what you write. Your creativity and expertise is what's important. Write text, though, that is not overly complex and will easily be understandable by second-language English readers.

Titles and 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 (for example Server System Variables, not Server system variables). Do not capitalize short function words such as to, the, and and.

Titles should not contain any type of formatting.

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, ending 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.

Contents

Most pages should have a table of contents. Embed the <<toc>> macro to add one. See the-toc-macro for details.

Use links generously to related content on the Knowledge Base. Links should be embedded in relevant text, for example:

"The innodb_buffer_pool_filename system variable"

rather than

"The innodb_buffer_pool_filename system variable".

Related links should also be added to a See Also section.

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.

When creating links to JIRA tasks in the Knowledge Base, do not use absolute references. The KB will automatically create a link using their "mdev" number. For example, the text 'mdev-191', when entered into the Knowledge Base becomes: MDEV-191.

Formatting and Highlighting

All SQL statements and functions that are referenced, should be linked to their respective page of the documentation.

Reserved words should always be typed in all capital letters, while the names of databases, tables, and columns should be in all lower-case letters.

SQL elements should preferably use the SQL macro. Other code elements, or SQL that formats poorly (such as SQL using /G) should use the Code macro.

See Editing Help for more help with formatting.

Content and Word Usage

Never use exclamation points and try to avoid using question marks in the content of articles.

Versioning

The Knowledge Base contains all information for all currently-supported versions. The product macro should be used to enclose information only applicable to a particular release. Product macros pertaining to old, unsupported releases should be removed from the text to avoid cluttering pages with unnecessary information.

Examples

Embed code samples in the appropriate macro, such as the code macro (for general syntax, code) or the sql macro (for SQL).

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.

Output that's not necessary for the example can also be removed for brevity, such as 1 row in set (0.000 sec).

For example:

SELECT 1;
+---+
| 1 |
+---+
| 1 |
+---+

rather than

mysql [localhost] {msandbox} ((none)) > SELECT 1;
+---+
| 1 |
+---+
| 1 |
+---+
1 row in set (0.000 sec)

Capitalize all reserved words within an example, including smaller words (e.g., AS, AND). Don't try to highlight or italicize any of the textnor 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.

Comments

Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.