Skip to content

Commit 849bb27

Browse files
vburzynskivburzynski
committed
add guide covering proposal for guideline pages
1 parent e7efd88 commit 849bb27

2 files changed

Lines changed: 101 additions & 1 deletion

File tree

‎.markdownlint-cli2.jsonc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@
149149

150150
/* MD052 - Reference links and images should use a label that is defined */
151151
"reference-links-images": {
152-
"shortcut_syntax": true
152+
"shortcut_syntax": false
153153
},
154154

155155
/* MD053 - Link and image reference definitions should be needed */

‎_template/Guide To Writing Guideline Pages.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Guide To Writing Guideline Pages
2+
3+
## What are guideline pages?
4+
5+
Guideline pages are comprised of the set of pages linked to from the outline-mode pages and which provide additional information and reasoning behind a guideline. The outline-mode pages are those pages which collate lists of guidelines under a specific topic.
6+
7+
A guideline page is a brief synopsis of a convention, standard, heuristic, best practice, or stylistic choice. It may cover the intent, influences, motivation, applicability, consequences, implementation or other particulars behind a guideline. It is not meant to be a comprehensive analysis; rather it should highlight of the most relevant details.
8+
9+
## Why promote a consistent format?
10+
11+
This *guide to writing guideline pages* suggests an informal simple formatted structure. The aim is to promote a small amount of consistency through format and layout while still being oriented towards flexibility. The content can be conversational and expresive through freeform text, while being presented in a familiar way. This consisitency can aid readers in their efforts to navigate the site because they can anticipate what they expect to find on any given page. When presented with information in a nonconventional or atypical way, they'll have to spend more time figuring out what they are looking at.
12+
13+
The selected structure is influenced by the pattern forms explored and discussed across various wikis such as WikiWikiWeb and resources such as the *Design Patterns* book by the Gang of Four. The format is largely borrowed from the Portland Form, also known as "Therefore But" due to it's construction: You summarize the context and forces in play, and then connect that with a bold "therefore" to the guideline. You can then optionally follow that with any constrasting details.
14+
15+
> [!TIP]
16+
> The guidelines are not formal design patterns, rather they are helpful principles and concepts that are not always well defined. With that in mind, feel free to take liberties with the suggested format. Furthermore, not every guideline requires further explanation.
17+
18+
## Guidelines
19+
20+
- The **file name** should match the **title** of the page exactly
21+
- as a result, titles must only use characters that are valid for use in a file name
22+
- The **title** should be a *proposition* (or claim) which concisely states the guideline
23+
- Titles should not be in interrogative form (such a question)
24+
- Titles should not be in lexical form (such as a noun or noun phrase)
25+
- **Guideline Section**
26+
- Prefer a **guideline section** that is short and concise but not terse
27+
- The first part of this section sets the stage by introducing the problem, context, and forces in play
28+
- The conflict is resolved by presenting the solution or guideline along with a discussion of the resulting context.
29+
- Then other considerations or counterindications can be reviewed.
30+
- It then ends with a summary and discussion of the greater context (to connect back to the broader scope).
31+
- Additional **headings** and sections can be added between the `## Guideline` and `## References` sections
32+
- Prefer repeating patterns found in other guides, but there's no conventions set here yet.
33+
- A **reference** section includes links to resources and pull-requests
34+
35+
## Page Template
36+
37+
```markdown
38+
# Use a prepositional pharse in sentence case for titles
39+
40+
## Guideline
41+
42+
An opening statement and introductory paragraph which discusses the forces in play around a problem. You might state and describe the problem while also quickly summarizing the surrounding context and why the problem exists.
43+
44+
**Therefore,** present an action to take or a guideline to follow. State the Thesis. Describe the solution and the resulting context. How are the earlier forces resolved? What is the rationale? You might include examples.
45+
46+
(*But...*) An optional section presenting other considerations or contrasting view. You might cover any counterindications to following the guidelines. Describe the position of the antithesis and opposition to the guideline. What happens if you take the guideline too far?
47+
48+
Finally (when relevant) summarize and discuss the greater context. How else can this help. What else is the guideline related to? This might also be a place to connect the guideline to guiding principles or other pages in the guides.
49+
50+
## Optional Additional Sections
51+
52+
Additional freeform sections can be added below the guideline pattern
53+
54+
## References
55+
56+
- [A list of links to supporting evidence, references, articles, or pull-requests](https://example.com)
57+
```
58+
59+
## Propositional Titles
60+
61+
A **proposition** is a statement or assertion that expresses a judgement or opinion[^1].
62+
63+
A propositional title:
64+
65+
- should make an assertion, claim, or declaration
66+
- written in *imperative mood* to express an action, command, suggestion, request, or instruction
67+
- can be a sentence or independent clause
68+
- should present a concise summary of the guideline
69+
70+
## Invalid or Problematic Characters for File Names and Titles
71+
72+
Avoid using characters that would be invalid or problematic in a file name.
73+
74+
| Character | Description | Why it is problematic |
75+
| --------: | :------------------- | ----------------------------------------------------- |
76+
| `/` | forward slash | used as a path name component separator |
77+
| `\` | backslash | used as a path name component separator |
78+
| `?` | question mark | used as a wildcard |
79+
| `*` | asterisk | used as a wildcard |
80+
| `%` | percent | used as a wildcard |
81+
| `<` | less than | redirects output |
82+
| `>` | greater than | redirects input |
83+
| `:` | colon | Windows uses this for mount point / drives |
84+
| `"` | double quote | legacy restriction carried over from DOS |
85+
| `\|` | vertical bar or pipe | used for software pipelining |
86+
| `.` | period | last occurrence is interpreted as extension separator |
87+
| `=` | equal sign | somecommand line interpreters use this as a separator |
88+
89+
## References
90+
91+
- Pattern Forms
92+
- <https://wiki.c2.com/?PortlandForm>
93+
- <https://wiki.c2.com/?ThereforeBut>
94+
- <https://wiki.c2.com/?PatternForms>
95+
- <https://c2.com/ppr/about/portland.html>
96+
- Invalid Filename Characters
97+
- <https://stackoverflow.com/questions/1976007/what-characters-are-forbidden-in-windows-and-linux-directory-names#:~:text=Sorted%20by:,Non%2Dprintable%20characters>
98+
- <https://en.wikipedia.org/wiki/Filename#Problematic_characters>
99+
100+
[^1]: Definition from [Oxford Languages](https://languages.oup.com/google-dictionary-en/) via Google Search

0 commit comments

Comments
 (0)