Skip to content

Commit 28f22c1

Browse files
feat: added in notes for blogs
added notes for articles on DevCenter
1 parent a24f92c commit 28f22c1

File tree

1 file changed

+15
-3
lines changed

1 file changed

+15
-3
lines changed

contributing/content-style.md

+15-3
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,7 @@ This content style guide should help make sure the Platform.sh docs are clear an
3737

3838
## About the audience
3939

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.
4241

4342
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.
4443

@@ -76,6 +75,13 @@ or inconveniences the reader.
7675

7776
So it's okay in phrases like `If you get an error, please open a support ticket.`
7877

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+
7985
## Aim for neutral text
8086

8187
In general, aim to present facts without inserting too much opinion.
@@ -87,6 +93,12 @@ Use | Avoid
8793
Be careful not to break anything | Of course, you naturally have to avoid breaking anything
8894
Making this small change can have large effects | Surprisingly, making this tiny change can have huge effects
8995

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+
90102
## Use inclusive language
91103

92104
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
209221

210222
For example, try to avoid using sentences starting with `There is/are` or `It is` too often.
211223
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.
213225

214226
Similar arguments apply to passive sentences.
215227
Sometimes, they work well, such as when the subject would be `the system`

0 commit comments

Comments
 (0)