You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CODE_OF_CONDUCT.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -4,4 +4,4 @@ This project has adopted the [OCaml Code of Conduct](https://github.com/ocaml/co
4
4
5
5
# Enforcement
6
6
7
-
This project follows the OCaml Code of Conduct [enforcement policy](https://github.com/ocaml/code-of-conduct/blob/main/CODE_OF_CONDUCT.md#enforcement).
7
+
This project follows the OCaml Code of Conduct [enforcement policy](https://github.com/ocaml/code-of-conduct/blob/main/CODE_OF_CONDUCT.md#enforcement).
Following these guidelines will help us maintain a high-quality and consistent OCaml Cookbook.
170
+
Following these guidelines will help us maintain a high-quality and consistent OCaml Cookbook.
171
171
172
172
### <aname="content-recurring-event"></a>Add A Recurring Event
173
173
@@ -192,10 +192,9 @@ The Changelog covers developments across:
192
192
-[OCaml Infrastructure](https://infra.ocaml.org/)
193
193
-[OCaml.org itself](https://ocaml.org/)
194
194
195
-
196
195
#### Purpose and Audience
197
196
198
-
The primary audience for the Changelog is OCaml users. Content should focus on changes, updates, and news that directly impact users of OCaml and its ecosystem.
197
+
The primary audience for the Changelog is OCaml users. Content should focus on changes, updates, and news that directly impact users of OCaml and its ecosystem.
199
198
200
199
Good candidates for Changelog posts include:
201
200
@@ -221,7 +220,6 @@ To contribute a new post to the Changelog:
221
220
4. Write the post content, focusing on how the news or change affects OCaml users.
222
221
5. Submit a pull request with your new file.
223
222
224
-
225
223
## Git and GitHub Workflow
226
224
227
225
The preferred workflow for contributing to a repository is to fork the main repository on GitHub, clone, and develop on a new branch.
This document explains how to write documentation such as tutorials, guides, or recommendations to be hosted in OCaml.org. It's also meant to be used as a style guide to ensure consistency in things like grammar, formatting, capitalisation, and spelling across all OCaml.org documentation.
3
+
This document explains how to write documentation such as tutorials, guides, or recommendations to be hosted in OCaml.org. It's also meant to be used as a style guide to ensure consistency in things like grammar, formatting, capitalisation, and spelling across all OCaml.org documentation.
4
4
5
-
Apply the [*Spiral Learning*](https://en.wikipedia.org/wiki/Spiral_approach) approach in tutorials. This teaching method first creates a solid foundation of a topic. By starting with an overview, it gives the reader the context and general information. Subsequent sections and tutorials review the important foundational information and expands, going into more detail and giving examples.
5
+
Apply the [*Spiral Learning*](https://en.wikipedia.org/wiki/Spiral_approach) approach in tutorials. This teaching method first creates a solid foundation of a topic. By starting with an overview, it gives the reader the context and general information. Subsequent sections and tutorials review the important foundational information and expands, going into more detail and giving examples.
6
6
7
7
## Materials
8
8
@@ -16,26 +16,28 @@ Apply the [*Spiral Learning*](https://en.wikipedia.org/wiki/Spiral_approach) app
16
16
17
17
## Audience
18
18
19
-
Anytime one contributes to the OCaml.org documentation, it's important to keep the target audience in mind. For example, if writing a tutorial for programmers new to OCaml, you want to ensure the examples are simple and straighforward so as not to overwhelm them with too much detail while starting their learning journey. For more advanced users, adjust the tone and examples accordingly.
19
+
Anytime one contributes to the OCaml.org documentation, it's important to keep the target audience in mind. For example, if writing a tutorial for programmers new to OCaml, you want to ensure the examples are simple and straighforward so as not to overwhelm them with too much detail while starting their learning journey. For more advanced users, adjust the tone and examples accordingly.
20
20
21
21
**Our audience:**
22
-
* Self-directed learners without a tutor
23
-
* Already know some programming basics (one other programming language)
24
-
* Likely a majority of consumers of libraries, hopefully some authors or people who turn into it
25
-
* English level B2 ideally
22
+
- Self-directed learners without a tutor
23
+
- Already know some programming basics (one other programming language)
24
+
- Likely a majority of consumers of libraries, hopefully some authors or people who turn into it
25
+
- English level B2 ideally
26
26
27
27
**Not our audience:**
28
-
* University students
29
-
* New to programming. We do not teach programming basics.
28
+
- University students
29
+
- New to programming. We do not teach programming basics.
30
30
31
31
## Goals
32
+
32
33
Especially since the release of OCaml 5.0 with Multicore support, perhaps our biggest goal is to increase the adoption of OCaml. In order to reach this goal, it's essential to have current, consistent, and comprehensive documentation.
33
34
34
35
1. Enable people to use OCaml for real projects / at the job / side projects
35
36
1. Get people who want to build and contribute to the ecosystem up to speed and building something good quickly
36
37
1.**Oddly Specific**: Enable people to do Advent of Code in OCaml.
37
38
38
-
## Our Key Values / Constraints:
39
+
## Our Key Values / Constraints
40
+
39
41
-**Goals and Prerequisites**. Each tutorial begins with its objectives, so that people know what they will learn about.```
40
42
-**Avoid Overwhelming Choices**. Tutorials should guide learners on a straightforward path, avoiding multiple options. This makes the learning process smoother. Detailed choices can be included in additional references and guides.
41
43
-**Highlight Important Computer Science Terms**. Use italics for well-known terms, providing a visual hint that these are important concepts. Linking to Wikipedia for further explanation is an option.
@@ -47,32 +49,31 @@ Especially since the release of OCaml 5.0 with Multicore support, perhaps our bi
47
49
## Common Phrases
48
50
49
51
- "Binding a value to a name" = declaring a variable
50
-
-`'a` is a type parameter called "alpha." It is not a _type variable_ (because the term _variable_ is a forbidden word).
52
+
-`'a` is a type parameter called "alpha." It is not a *type variable* (because the term *variable* is a forbidden word).
51
53
- Pass a function as a value to another function as a parameter - not a "function value"
52
54
53
-
54
55
## Things to Avoid
55
56
56
-
1. Don't use the same letter for different things, i.e., when talking about a type parameter `'a`, don't have a name `a` nearby. In fact, since `a` can easily be confused with `'a` (alpha), start with `f` when using letters as parameters.
57
+
1. Don't use the same letter for different things, i.e., when talking about a type parameter `'a`, don't have a name `a` nearby. In fact, since `a` can easily be confused with `'a` (alpha), start with `f` when using letters as parameters.
57
58
1. Never use the term "variable," instead
58
59
a. Names and values (binding = a value is bound to a name)
59
60
b. Type parameter
60
61
1. Use “parameter” and “argument” appropriately. Parameters occur in function declarations. Arguments are values that functions are applied to.
61
62
1. Don't use math, computer science, or programming language theory terminology without reason and explanation.
62
63
64
+
## Writing, Grammar, and Spelling
63
65
64
-
## Writing, Grammar, and Spelling
65
-
66
-
Please don't worry about this too much, as a technical writer will review any new documentation or changes to catch these types of things. It's included here for reference, if interested.
66
+
Please don't worry about this too much, as a technical writer will review any new documentation or changes to catch these types of things. It's included here for reference, if interested.
67
67
68
68
### Tone & POV
69
-
We're aiming for a relatively casual tone in these tutorials and other documentation. This means that it should read like you're speaking directly to the reader rather than an academic tone. To this end, it is acceptable to use second person (you), sparingly.
70
69
71
-
It's also okay to use first person plural (we, us), sparingly, but don't use the first person singular (I, me), as there isn't an author byline for the reader to know who "I" is. Using "we" can be helpful to write active sentences (more below).
70
+
We're aiming for a relatively casual tone in these tutorials and other documentation. This means that it should read like you're speaking directly to the reader rather than an academic tone. To this end, it is acceptable to use second person (you), sparingly.
72
71
72
+
It's also okay to use first person plural (we, us), sparingly, but don't use the first person singular (I, me), as there isn't an author byline for the reader to know who "I" is. Using "we" can be helpful to write active sentences (more below).
73
73
74
74
### Active Voice & Unnecessary Words
75
-
Active sentences employ a clear subject that performs an action with a robust verb (e.g., Mary baked the cake.), as opposed to weak verbs such as *occur* and *happen.* Passive sentences typically incorporate '***to be'*** verbs (is, are, were, was, etc.), where the subject undergoes the action (e.g., he cake was baked by Mary). Although it's not possible to avoid all **to be** verbs, try to minimise them when possible.
75
+
76
+
Active sentences employ a clear subject that performs an action with a robust verb (e.g., Mary baked the cake.), as opposed to weak verbs such as *occur* and *happen.* Passive sentences typically incorporate '***to be'*** verbs (is, are, were, was, etc.), where the subject undergoes the action (e.g., he cake was baked by Mary). Although it's not possible to avoid all **to be** verbs, try to minimise them when possible.
76
77
77
78
The sentences below highlight issues and provide suggestions for improvement:
78
79
@@ -84,37 +85,35 @@ The sentences below highlight issues and provide suggestions for improvement:
84
85
85
86
It's best to eliminate unnecessary prepositional phrases, especially when using with the possessive. Avoid phrases like "the car of Susan." Instead, write "Susan's car." When prepositional phrases (e.g., those starting with by, for, in, of, on, etc.) are strung together, it makes for clumsy and awkward sentences. For example: "She went *on* a road trip *across* the mountains *to* take pictures." This sentence has three prepositional phrases back to back. You can improve it by removing at least one prepositional phrase, like this: "She took pictures on her roadtrip across the mountains."
86
87
87
-
Following these guidelines makes for more enjoyable reading experience.
88
+
Following these guidelines makes for more enjoyable reading experience.
88
89
89
90
### Spelling & Grammar
90
91
91
92
-[Grammar Help at Grammarly](https://www.grammarly.com/blog/category/handbook/)
92
93
-**Punctuation Preferences:**
93
-
- Oxford (serial) comma [We bought bread, milk, and peanut butter], so there is a final comma before the conjunction.
94
-
- Single space after a `.` period (full stop).
95
-
- Always use `'` for singular names/nouns ending in `s` and for plural nouns ending in `s` (e.g., Thomas’ and Companies’). Although the grammatically correct way to say and spell singular nouns ending in `s` is “Thomas’s”, it does look weird. It’s the consensus to treat every `s` as if it were a plural possessive, so instead write "Thomas'." Whenever possible, rephrase the sentence to avoid it completely.
96
-
- Place punctuation inside of quotation marks: OCaml is an "industrial-strength functional programming language with an emphasis on expressiveness and safety." (not "...safety".)
97
-
- Use **en dashes `–`** surrounded by spaces for 'asides' (as an alternative, you can use parentheses). Example: OCaml Multicore is – as my grandmother would say – an excellent upgrade.
-[Differences in British & American](https://www.unr.edu/writing-speaking-center/student-resources/writing-speaking-resources/british-american-english), please use the British spelling. See below.
- Oxford (serial) comma [We bought bread, milk, and peanut butter], so there is a final comma before the conjunction.
95
+
- Single space after a `.` period (full stop).
96
+
- Always use `'` for singular names/nouns ending in `s` and for plural nouns ending in `s` (e.g., Thomas’ and Companies’). Although the grammatically correct way to say and spell singular nouns ending in `s` is “Thomas’s”, it does look weird. It’s the consensus to treat every `s` as if it were a plural possessive, so instead write "Thomas'." Whenever possible, rephrase the sentence to avoid it completely.
97
+
- Place punctuation inside of quotation marks: OCaml is an "industrial-strength functional programming language with an emphasis on expressiveness and safety." (not "...safety".)
98
+
- Use **en dashes `–`** surrounded by spaces for 'asides' (as an alternative, you can use parentheses). Example: OCaml Multicore is – as my grandmother would say – an excellent upgrade.
-[Differences in British & American](https://www.unr.edu/writing-speaking-center/student-resources/writing-speaking-resources/british-american-english), please use the British spelling. See below.
- focussed / focusses (instead of the single s: focused / focuses)
112
-
- vs, not vs. as in American English. Same with Dr, Mr, Ms, Mrs instead of Dr., Mr., Ms., Mrs.
113
-
- Although programme is traditionally the UK spelling, **program** is more common.
114
-
115
-
-**Capitalisation**
116
-
- Capitalise every word (except “little words” like of, and, or, etc.) in titles, aka “[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case).” Strangely, it is correct to capitalise “with” in a title.
117
-
- Use Title Case in headings / subheadings. Try to keep them under 7 words.
118
-
- Capitalise the first letter of bullet points, aka “[Sentence Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case).” However, if it’s not a complete sentence in the bullet point, don’t use a period (full stop) unless it’s followed by other sentences.
- focussed / focusses (instead of the single s: focused / focuses)
113
+
- vs, not vs. as in American English. Same with Dr, Mr, Ms, Mrs instead of Dr., Mr., Ms., Mrs.
114
+
- Although programme is traditionally the UK spelling, **program** is more common.
120
115
116
+
-**Capitalisation**
117
+
- Capitalise every word (except “little words” like of, and, or, etc.) in titles, aka “[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case).” Strangely, it is correct to capitalise “with” in a title.
118
+
- Use Title Case in headings / subheadings. Try to keep them under 7 words.
119
+
- Capitalise the first letter of bullet points, aka “[Sentence Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case).” However, if it’s not a complete sentence in the bullet point, don’t use a period (full stop) unless it’s followed by other sentences.
0 commit comments