diff --git a/content/improving-documentation/style-guide.md b/content/improving-documentation/style-guide.md index 57cd7a9..23568c6 100644 --- a/content/improving-documentation/style-guide.md +++ b/content/improving-documentation/style-guide.md @@ -41,6 +41,16 @@ Feel free to suggest any additional points and/or sections you deem necessary. Follow these guidelines to organize the structure of your document: +### Code Blocks + +- **Configuration files:** Small configuration files should be enclosed in Markdown code blocks. +- **Command line input:** + - If you include a command that is meant to be executed by an ordinary user, prepend the character `$`. + - Likewise, if a command is meant to be executed by `root` / an administrator, prepend the character `#`. +- **Command line output:** + - If the output is of direct relevance to the user, avoid screenshots. Use a Markdown code block instead. + - If the output is too large, try trimming irrelevant lines first and explain what the reader should look out for. + ### Images and UI Descriptions Screenshots and other images can heavily improve the quality of an article without much effort. @@ -58,7 +68,6 @@ Before including screenshots, we highly recommend writing articles in text first - Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues (i.e. arrows, icons) in screenshots. - When possible, use text to describe what you expect the reader to see after following an instruction or a set of instructions. - When using images, always use an adequate amount of alt text. -- Use Markdown code blocks for code, configuration files and terminal output. {% admonition "warning" %}