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: contributing/content-style.md
+15-3
Original file line number
Diff line number
Diff line change
@@ -37,8 +37,7 @@ This content style guide should help make sure the Platform.sh docs are clear an
37
37
38
38
## About the audience
39
39
40
-
The goal of Platform.sh's documentation is to help tech-savvy users self-educate
41
-
on how to use and get the most out of Platform.sh.
40
+
The goal of Platform.sh and Upsun's documentation is to help tech-savvy users self-educate on how to use and get the most out of Platform.sh.
42
41
43
42
Readers are generally familiar with common web development tools and practices, but it's best not to assume an in-depth knowledge of processes related to Upsun or Platform.sh. Remember, our audience may be comprised of more than developers, so try to explain concepts as simply as possible.
44
43
@@ -76,6 +75,13 @@ or inconveniences the reader.
76
75
77
76
So it's okay in phrases like `If you get an error, please open a support ticket.`
78
77
78
+
{{< note theme="info" title="Using first person in articles" >}}
79
+
It should be noted that the first person plural ("we", "us", and "our") can be used in articles on DevCenter. The style of this content is more conversational in tone, and suits the use of the collective first person when guiding the user through a process.
80
+
For example, the sentences below are acceptable for articles:
81
+
- 'Our content will be loaded directly in the assistant on OpenAI.'
82
+
- 'Now that our Chainlit application is deployed and available, it would be great to add some form of authentication to make sure only you and your folks can access it.'
83
+
{{< /note >}}
84
+
79
85
## Aim for neutral text
80
86
81
87
In general, aim to present facts without inserting too much opinion.
@@ -87,6 +93,12 @@ Use | Avoid
87
93
Be careful not to break anything | Of course, you naturally have to avoid breaking anything
88
94
Making this small change can have large effects | Surprisingly, making this tiny change can have huge effects
89
95
96
+
{{< note theme="info" title="Using neutral text in articles" >}}
97
+
98
+
It should be noted that the technical articles on DevCenter are allowed less neutrality than the documentation, as this content is naturally more conversational in tone.
99
+
100
+
{{< /note >}}
101
+
90
102
## Use inclusive language
91
103
92
104
In keeping with the Platform.sh value of being diverse,
@@ -209,7 +221,7 @@ By avoiding overly wordy phrases, you help make it clearer what needs to be done
209
221
210
222
For example, try to avoid using sentences starting with `There is/are` or `It is` too often.
211
223
While there are times when this makes sense, often you can rephrase the sentence to be more direct.
212
-
Such phrases work well for rhythm and emphasis, but that is usually less important in technical writing.
224
+
Such phrases work well for rhythm and emphasis, but that is usually less important in technical writing for both documentation and technical blogs or articles.
213
225
214
226
Similar arguments apply to passive sentences.
215
227
Sometimes, they work well, such as when the subject would be `the system`
0 commit comments