|
6 | 6 | --- |
7 | 7 |
|
8 | 8 | # Manual of Style |
9 | | -# Purpose |
10 | | - |
11 | 9 | This manual of style provides editors with guidelines that will help readers use RTFM more intuitively. |
| 10 | +The manual is broken down into smaller articles for ease of navigation. |
| 11 | +## Navigation |
12 | 12 |
|
13 | | -# Formatting |
14 | | -## Paragraphs |
15 | | -Text not separated by a blank line will be grouped together as if they were a single paragraph. |
16 | | -an |
17 | | - |
18 | | -For ease of editing for future editors, please put each sentence on a separate line when writing a document. |
19 | | - |
20 | | -source: |
21 | | - |
22 | | -``` |
23 | | -This is a sentence. |
24 | | -This sentence follows that sentence. |
25 | | -This sentence is also part of the same paragraph. |
26 | | -
|
27 | | -This sentence is starts new paragraph. |
28 | | -There is a blank line between this paragraph and the previous one. |
29 | | -This sentence concludes the paragraph. |
30 | | -``` |
31 | | - |
32 | | -result: |
33 | | - |
34 | | -This is a sentence. |
35 | | -This sentence follows that sentence. |
36 | | -This sentence is also part of the same paragraph. |
37 | | - |
38 | | -This sentence is starts new paragraph. |
39 | | -There is a blank line between this paragraph and the previous one. |
40 | | -This sentence concludes the paragraph. |
41 | | -## Headings |
42 | | -| element | syntax | |
43 | | -|-----------------|------------------------| |
44 | | -| level 1 heading | `# level 1 heading` | |
45 | | -| level 2 heading | `## level 2 heading` | |
46 | | -| level 3 heading | `### level 3 heading` | |
47 | | -| level 4 heading | `#### level 4 heading` | |
48 | | -| etc. | ... | |
49 | | - |
50 | | -## Basic Formatting |
51 | | - |
52 | | -| element | syntax | result | |
53 | | -|---------------------------------|---------------------|-------------------| |
54 | | -| bold | `**bold**` | **bold** | |
55 | | -| italic | `*italic**` | *italic* | |
56 | | -| verbatim (inline code) | `` `code` `` | `code` | |
57 | | - |
58 | | -### pythhon-markdown Extended Syntax |
59 | | -| element | syntax | result | |
60 | | -|---------------|---------------------|-------------------| |
61 | | -| highlight | `==highlight==` | ==highlight== | |
62 | | -| underline | `^^underline^^` | ^^underline^^ | |
63 | | -| strikethrough | `~~strikethrough~~` | ~~strikethrough~~ | |
64 | | -| subscript | `sub~script~` | sub~script~ | |
65 | | -| superscript | `super^script^` | super^script^ | |
66 | | -| keyboard | `++enter++` | ++enter++ | |
67 | | - |
68 | | -## Lists |
69 | | -### ordered lists |
70 | | -ordered lists are denoted by a group of lines where each line starts out with a number and a period. |
71 | | -markdown will automatically publish the correct number order even if the raw input is out of order. |
72 | | - |
73 | | -syntax: |
74 | | -``` |
75 | | -1. item 1 |
76 | | -8. item 2 |
77 | | -3. item 3 |
78 | | -``` |
79 | | - |
80 | | -result: |
81 | | - |
82 | | -1. item 1 |
83 | | -8. item 2 |
84 | | -3. item 3 |
85 | | - |
86 | | -### unordered list |
87 | | - |
88 | | -syntax: |
89 | | -``` |
90 | | -- an item |
91 | | -- another item |
92 | | -- an other item |
93 | | -- another other item |
94 | | -``` |
95 | | -result: |
96 | | - |
97 | | -- an item |
98 | | -- another item |
99 | | -- an other item |
100 | | -- another other item |
101 | | - |
102 | | -## mkdocs-material Extensions |
103 | | -### Admonitions |
104 | | -### Grids |
105 | | -# Front Matter |
106 | | -Pages should have a front matter placed before the first heading. |
107 | | -Front matter is a snippet of yaml that is usually intended to add meta data to a `.md` document. |
108 | | -It is a block of yaml variables wrapped with two `---`. |
109 | | - |
110 | | -Every page should have tags listed in its front matter. |
111 | | -A brief description can also be provided. |
112 | | - |
113 | | -```yaml |
114 | | ---- |
115 | | -description: A brief description can be provided here. |
116 | | -tags: |
117 | | - - tag |
118 | | ---- |
119 | | -``` |
120 | | - |
121 | | -There should be a few tags to help readers understand what kind of page it is. |
122 | | -Tags should be all lowercase and tags should be ordered from general to more specific. |
123 | | -If there is insufficient information, the top tag should be `STUB` in capital letters. |
124 | | -`STUB` should be the only tag that uses capital letters. |
125 | | - |
126 | | -for example: |
127 | | - |
128 | | -```yaml |
129 | | ---- |
130 | | -description: This machine prints things |
131 | | -tags: |
132 | | - - STUB |
133 | | - - equipment |
134 | | - - print and office |
135 | | - - print |
136 | | - - paper |
137 | | ---- |
138 | | -# A Print Machine |
139 | | -``` |
140 | | - |
141 | | -# Equipment |
142 | | -## Titles and file names |
143 | | -### Filenames |
144 | | -File names should be .md files using a common name. |
145 | | -The name of the file is the name of the page's url link (rtfm.sysshop.org/users/Equipment/[filename]) This is different from the title of the page. |
146 | | - |
147 | | -### Titles |
148 | | -Level 1 headings should be reserved exclusively for naming individual pieces of equipment or The page in general. |
149 | | -All headings in Contents will be level 2 headings or lower in priority. |
150 | | - |
151 | | -The first level 1 heading will be recognized as a page title. |
152 | | -The title of a page depends on whether the page lists a single machine or multiple machines of different models. |
153 | | -If the page is only about 1 model of machine the title should have the following format: |
154 | | -`Manufacturer Model Maximum size Common name` |
155 | | - |
156 | | -If the page contains multiple machines then the 1st primary heading should be the common name of the machine. Each subsequent primary subheading should have the following format: |
157 | | -`Manufacturer Model number Maximum size` |
158 | | - |
159 | | -## Contents |
160 | | -For new equipment entries copy equipment_template.md and rename it to the appropriate file name. |
161 | | - |
162 | | -A template for equipment pages is provided at: |
163 | | - |
164 | | -### Manuals |
165 | | -Links to the equipment's full manual should be provided under this heading. |
166 | | - |
167 | | -### Firmware, Drivers, and Software |
168 | | -Relevant programs related to the equipment should get listed here. |
169 | | -Information about whether the software is already available on SYN Shop computers should also be indicated under this heading. |
170 | | -Distinguish between necessary and optional firmware in the subheadings below. |
171 | | -A sentence describing the software should be provided after each link. |
172 | | -A more detailed description of each software should be provided in a separate page for each individual software. |
173 | | - |
174 | | -#### Required |
175 | | -Firmware, drivers, and software necessary to operate the equipment should be listed under this heading. |
176 | | -For example: |
177 | | -Firmware - The firmware that is installed on the equipment, please ask a board member if you believe the firmware should be updated. |
178 | | -Driver - The driver that needs to be installed on computers that interact with this equipment. |
179 | | -Software - The software necessary to operate this equipment. |
180 | | - |
181 | | -#### Optional |
182 | | -Software that is relevant, but optional can be listed under this heading. |
183 | | -If there are multiple programs that serve the same function, consider making subheadings. |
184 | | - |
185 | | -### Function |
186 | | -This section should express to a reader what the machine does, and why someone would use it. |
187 | | - |
188 | | -#### Specifications |
189 | | -List information about the sizes of material it can take under this heading. |
190 | | - |
191 | | -### Cost and Consumables |
192 | | -This section should describe any additional costs past a membership to use this machine. |
193 | | -It should articulate what materials are potentially consumed during usage. |
194 | | - |
195 | | -### Usage |
196 | | -This section should describe the specific usage of a machine and provide adequate instructions on how to use that machine. |
197 | | - |
198 | | -### Maintenance |
199 | | -This section should list maintenance tasks. This ideally should be summarized with a markdown table with the name description and frequency of the task. |
200 | | -A detail set of instructions can be provided in subheadings. |
201 | | - |
202 | | -| task | description | frequency | |
203 | | -|--------|---------------------------------------|-----------------| |
204 | | -| task 1 | This is a task that needs to be done. | hourly | |
205 | | -| task 2 | This task also needs to be done | every few years | |
206 | | -| | | | |
207 | | - |
208 | | -#### Maintenance Log |
209 | | -Any notable issues should be posted under this heading. |
210 | | - |
211 | | -### Troubleshooting |
212 | | -This provides a list of common issues and steps to fixing them. |
213 | | - |
214 | | - |
215 | | -# Software |
216 | | -Software pages on RTFM should provide information relevant to using it at the shop. |
217 | | -The do not need to be comprehensive restatements of the original documentation. |
218 | | -Additional features can refer to the original software's documentation. |
| 13 | +- [Formatting](/editors/Style/Formatting) |
| 14 | +- [Articles](/editors/Style/Articles) |
| 15 | + - [Equipment Articles](/edtors/Style/Equipment Articles) |
| 16 | + - [Software Articles](/edtors/Style/Software Articles) |
0 commit comments