Skip to content

Commit c9263ee

Browse files
LoquacityLoquacity
authored
Create CONTRIBUTING.md & add docs contributors' guide (timescale#54)
* Create CONTRIBUTING.md Adds a proper contributing file. This will make GH happy, and also provide a starting point for getting some more writing guidance in. * GH instructions * standards * resources, language, grammar * verbs * small edits * index * make the linter a bit happier * Linter loves whitespace * wug setup * typo * Edits per feedback
1 parent fa253e5 commit c9263ee

File tree

3 files changed

+343
-0
lines changed

3 files changed

+343
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Introduction
2+
There are multiple ways to help make TimescaleDB better. All of our
3+
documentation and source for the PostgreSQL extension are available to use and
4+
review with GitHub.
5+
6+
## First contribution
7+
You can make contributions to the documentation by creating a fork of the
8+
repository.
9+
10+
11+
### Procedure: Contributing using a fork
12+
1. Make sure you have a [github](github.com) account, and that you're signed in.
13+
1. Navigate to the [Timescale Documentation
14+
Repo](https://github.com/timescale/docs) click the `Fork` button in the
15+
top-right corner, and select the account you want to use.
16+
1. Wait for GitHub to create your fork and redirect you.
17+
1. Clone the repository to your local machine. To find this URL, click the green
18+
`Code` button and copy the HTTPS URL:
19+
```bash
20+
git clone https://github.com/<username>/docs.git
21+
```
22+
1. List the current remote branches:
23+
```bash
24+
git remote -v
25+
```
26+
This command should list two remotes, both marked `origin`, like this:
27+
```bash
28+
origin https://github.com/<username>/docs.git (fetch)
29+
origin https://github.com/<username>/docs.git (push)
30+
```
31+
The `origin` remotes are your own fork, and you can do whatever you want here without changing the upstream repository.
32+
1. Add the docs repo as an upstream:
33+
```bash
34+
git remote add upstream https://github.com/timescale/docs.git
35+
```
36+
1. Check:
37+
```bash
38+
git remote -v
39+
```
40+
This command should now have the same two `origin` remotes as before, plus two more labelled `upstream`, like this:
41+
```bash
42+
origin https://github.com/<username>/docs.git (fetch)
43+
origin https://github.com/<username>/docs.git (push)
44+
upstream https://github.com/timescale/docs.git (fetch)
45+
upstream https://github.com/timescale/docs.git (push)
46+
```
47+
1. Fetch the branches in the upstream repository:
48+
```bash
49+
git fetch upstream
50+
```
51+
1. Merge the changes from the upstream `latest` branch, into your fork's
52+
`latest` branch:
53+
```bash
54+
git merge upstream/latest
55+
```
56+
1. Create a new branch for the work you want to do. Make sure you give it an
57+
appropriate name, and include your username:
58+
```bash
59+
git checkout -b update-readme-username
60+
```
61+
62+
### Procedure: Committing changes and creating a pull request
63+
1. Make your changes.
64+
1. Add the updated files to your commit:
65+
```bash
66+
git add .
67+
```
68+
1. Commit your changes:
69+
```bash
70+
git commit -m "Commit message here"
71+
```
72+
1. Push your changes:
73+
```bash
74+
git push
75+
```
76+
If git prompts you to set an upstream in order to push, use this command:
77+
```bash
78+
git push --set-upstream origin <branchname>
79+
```
80+
1. Create a pull request (PR) by navigating to <https://github.com/timescale/docs>
81+
and clicking `Compare and Create Pull Request`. Write an informative commit
82+
message detailing your changes, choose reviewers, and save your PR. If you
83+
haven't yet finished the work you want to do, make sure you create a draft PR by
84+
selecting it from the drop down box in the GitHub web UI. This lets your
85+
reviewers know that you haven't finished work yet, while still being transparent
86+
about what you are working on, and making sure we all understand current
87+
progress.
88+
89+
:warning: Choose your reviewers carefully! If you have made changes to the technical
90+
detail of the documentation, choose an appropriate subject matter expert (SME)
91+
to review those changes. Additionally, every change requires at least one
92+
documentation team member to approve.
93+
94+
## Second contribution
95+
Once you have checked out the repo and want to keep working on things, you need
96+
to ensure that your local copy of the repo stays up to date. If you don't do
97+
this, you *will* end up with merge conflicts.
98+
99+
### Procedure: Second contribution
100+
1. Check out your fork's `latest` branch:
101+
```bash
102+
git checkout latest
103+
```
104+
You will get a message like this:
105+
```bash
106+
Switched to branch 'latest'
107+
Your branch is up to date with 'origin/latest'.
108+
```
109+
BEWARE! This is usually a lie!
110+
1. Fetch the branches in the upstream repository:
111+
```bash
112+
git fetch upstream
113+
```
114+
1. Merge the changes from the upstream `latest` branch, into your fork's
115+
`latest` branch:
116+
```bash
117+
git merge upstream/latest
118+
```
119+
1. If you are continuing work you began earlier, check out the branch that
120+
contains your work. For new work, create a new branch. Doing this regularly as
121+
you are working will mean you keep your local copies up to date and avoid
122+
conflicts. You should do it at least every day before you begin work, and again
123+
whenever you switch branches.
124+
125+
:warning: Never leave branches lying around on your local system. Create your PR as soon
126+
as possible, and make good use of the Draft feature. Commit to your feature
127+
branch early and often! Update your local copy from latest whenever you switch
128+
branches.
129+
130+
## Writing standards
131+
Timescale is in the process of creating comprehensive writing and style standards. For the current guidelines, see [contributing to documentation][docs-standards].
132+
133+
## The Timescale documentation team
134+
* Ryan Booz <https://github.com/ryanbooz>
135+
* Lana Brindley <https://github.com/Loquacity>
136+
* Hel Rabelo <https://github.com/helrabelo>
137+
* Ted Sczelecki <https://github.com/tedsczelecki>
138+
139+
140+
[docs-standards]: timescaledb/contribute-to-docs

‎timescaledb/contribute-to-docs.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Contributing to Timescale documentation
2+
Timescale documentation is hosted in a [GitHub repository][github-docs] and is
3+
open for contribution from all community members. If you find errors or would
4+
like to add content to our docs, you can create a pull request using GitHub for
5+
review by our documentation team. This document contains everything you need to
6+
know about our writing style and standards, but don't worry too much if you
7+
aren't sure what to write. Our documentation team will help you craft the
8+
perfect words when you have a PR ready. We also have some automation on our
9+
repository to help you.
10+
11+
If you want to make minor changes to docs, such as fixing a typo, you can make
12+
corrections and submit pull requests on the GitHub website. Go to the file you
13+
want to correct and click the 'pencil' icon to edit. Make the corrections, and
14+
use the options at the bottom of the page to submit a pull request.
15+
16+
To make larger changes to the documentation, follow the instructions in
17+
our [Contributors' Guide][contributors].
18+
19+
For technical details about the repository, including understanding how the
20+
repository is organized, and the various markup and formatting conventions, see
21+
the [README][readme].
22+
23+
Before we accept any contributions, Timescale contributors need to sign the
24+
Contributor License Agreement (CLA). By signing a CLA, we can ensure that the
25+
community is free and confident in its ability to use your contributions. You
26+
will be prompted to sign the CLA during the pull request process.
27+
28+
## Resources
29+
When making style decisions, consult resources in this order:
30+
1. This guide: always check this guide first, it contains project-specific
31+
guidance, and in some cases differs from the other resources listed here.
32+
1. The [Google Developer Documentation Style Guide][google-style]: for most
33+
general style guidance, we rely on the style defined here.
34+
1. The Chicago Manual of Style: we use this guide for some formatting decisions
35+
that are not covered in other resources
36+
1. Merriam-Webster: Timescale documentation is written in US English, for
37+
spelling and definitions, consult the dictionary.
38+
39+
## Language
40+
We use standard US English, with an emphasis on plain (or classical) language, in simple present tense, using the second person singular ("you"). We prefer the active voice, but do not be afraid to use the passive voice if it serves a purpose. Always choose the simplest and clearest language, regardless of whether it's passive or active voice.
41+
42+
For example, here are three ways of writing one sentence:
43+
* Natural English: In order to perform X installation process, please ensure
44+
that all of the following steps are done ...
45+
* Tech writer's English: To perform the X installation process, verify you have
46+
done the subsequent steps ...
47+
* Plain English: To install X, do these steps ...
48+
49+
Remember that the order of words is important in English. Put the most important
50+
part of a sentence first, this is usually the actor or the action. Use the
51+
second part of the sentence to give it a focus: what else should the reader
52+
notice?
53+
54+
Readers are often in an agitated state by the time they get to our
55+
documentation. Stressed readers jump around in the text, skip words, steps, or
56+
paragraphs, and will quickly give up if things seem too complex. To mitigate
57+
this, use short sentences, plain language, and a minimum number of eye-catching
58+
details such as admonitions.
59+
60+
Never assume that because you've explained something earlier in a document,
61+
readers will know it later in the document. You can use cross-references to help
62+
guide readers to further information if they need it.
63+
64+
## Grammar
65+
Grammar rules are tacit evolving conventions. They have no implicit value by
66+
themselves, they only gain value because everyone is doing it.
67+
68+
There are no hard and fast rules about dangling participles, split infinitives,
69+
or ending sentences with prepositions. Obeying these rules can often make
70+
language clearer but, in some cases, they make language more complicated. In
71+
that case, feel free to ignore them.
72+
73+
## Verbs
74+
* `Click` a button in a graphical user interface using a mouse. Do not `Click on`.
75+
* `Press` a key or key combination on a keyboard.
76+
* `Type` words or numbers using a keyboard.
77+
* `Check` or `uncheck` a checkbox.
78+
* `Select` or `deselect` an item in a menu.
79+
* `Navigate` to a page or location in a graphical user interface.
80+
81+
82+
## Word usage
83+
84+
### A [](#A)
85+
86+
*Adverbs*
87+
: Do not use.
88+
89+
:+1: Install TimescaleDB.
90+
91+
:x: Simply install TimescaleDB.
92+
93+
*And/Or*
94+
: Do not use. You can usually pick one. If you're not sure, pick "and".
95+
96+
:x: I like apples and/or oranges.
97+
98+
:+1: I like apples and oranges.
99+
100+
### B [](#B)
101+
102+
### C [](#C)
103+
104+
*Contractions*
105+
: Absolutely fine to use, but try not to overdo it.
106+
107+
### D [](#D)
108+
109+
### E [](#E)
110+
111+
### F [](#F)
112+
113+
*File system*
114+
: Two words.
115+
116+
### G [](#G)
117+
118+
### H [](#H)
119+
120+
### I [](#I)
121+
122+
### J [](#J)
123+
124+
### K [](#K)
125+
126+
### L [](#L)
127+
128+
*Latin abbreviations*
129+
: Do not use.
130+
131+
:+1: For example
132+
133+
:x: eg
134+
135+
### M [](#M)
136+
137+
### N [](#N)
138+
139+
### O [](#O)
140+
141+
### P [](#P)
142+
143+
### Q [](#Q)
144+
145+
### R [](#R)
146+
147+
### S [](#S)
148+
149+
### T [](#T)
150+
151+
*Timescale*
152+
: The name of the company. Do not use camel case.
153+
154+
:+1: Timescale is hosting a virtual event.
155+
156+
:x: I have installed Timescale to manage my time-series data.
157+
158+
:x: TimeScale
159+
160+
*TimescaleDB*
161+
: The name of the product. Capitalize the initial letter, and the "DB" at the end.
162+
163+
:+1: "I have installed TimescaleDB to manage my time-series data."
164+
165+
:x: "TimescaleDB is hosting a virtual event."
166+
167+
:x: "TimeScaleDB"
168+
169+
### U [](#U)
170+
171+
*Utilize*
172+
: Do not use. Use "use" instead.
173+
174+
### V [](#V)
175+
176+
*Via*
177+
: Avoid if possible. There is usually a more accurate English word, like
178+
"through", "with", or "using".
179+
180+
### W [](#W)
181+
182+
*Will*
183+
: Do not use. It usually indicates that you are writing in future tense.
184+
Always write in simple present tense.
185+
186+
:+1: After installation, you see a message.
187+
188+
:x: After installation, you will see a message.
189+
190+
### X [](#X)
191+
192+
### Y [](#Y)
193+
194+
### Z [](#Z)
195+
196+
[github-docs]: https://github.com/timescale/docs
197+
[contributors]: https://github.com/timescale/docs/CONTRIBUTING.md
198+
[readme]: https://github.com/timescale/docs/README.md
199+
[google-style]: https://developers.google.com/style

‎timescaledb/page-index/page-index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ module.exports = [
3333
{
3434
title: "Contribute to TimescaleDB",
3535
href: "contribute-to-timescaledb"
36+
},
37+
{
38+
title: "Contribute to documentation",
39+
href: "contribute-to-docs"
3640
}
3741
]
3842
}

0 commit comments

Comments
 (0)