Contributing to Timescale documentation
Timescale documentation is hosted in a GitHub repository and is open for contribution from all community members. If you find errors or would like to add content to our docs, you can create a pull request using GitHub for review by our documentation team. This document contains everything you need to know about our writing style and standards, but don't worry too much if you aren't sure what to write. Our documentation team helps you craft the perfect words when you have a PR ready. We also have some automation on our repository to help you.
If you want to make minor changes to docs, such as fixing a typo, you can make corrections and submit pull requests on the GitHub website. Go to the file you want to correct and click the 'pencil' icon to edit. Make the corrections, and use the options at the bottom of the page to submit a pull request.
To make larger changes to the documentation, follow the instructions in our Contributors' Guide.
For technical details about the repository, including understanding how the repository is organized, and the various markup and formatting conventions, see the README.
Before we accept any contributions, Timescale contributors need to sign the Contributor License Agreement (CLA). By signing a CLA, we can ensure that the community is free and confident in its ability to use your contributions. You are prompted to sign the CLA during the pull request process.
When making style decisions, consult resources in this order:
- This guide: always check this guide first, it contains project-specific guidance, and in some cases differs from the other resources listed here.
- The Google Developer Documentation Style Guide: for most general style guidance, we rely on the style defined here.
- The Chicago Manual of Style: we use this guide for some formatting decisions that are not covered in other resources
- Merriam-Webster: Timescale documentation is written in US English, for spelling and definitions, consult the dictionary.
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.
For example, here are three ways of writing one sentence:
- Natural English: In order to perform X installation process, please ensure that all of the following steps are done ...
- Tech writer's English: To perform the X installation process, verify you have done the subsequent steps ...
- Plain English: To install X, do these steps ...
Remember that the order of words is important in English. Put the most important part of a sentence first, this is usually the actor or the action. Use the second part of the sentence to give it a focus: what else should the reader notice?
Readers are often in an agitated state by the time they get to our documentation. Stressed readers jump around in the text, skip words, steps, or paragraphs, and can quickly give up if things seem too complex. To mitigate this, use short sentences, plain language, and a minimum number of eye-catching details such as admonitions.
Never assume that because you've explained something earlier in a document, readers know it later in the document. You can use cross-references to help guide readers to further information if they need it.
Grammar rules are tacit evolving conventions. They have no implicit value by themselves, they only gain value because everyone is doing it.
There are no hard and fast rules about dangling participles, split infinitives, or ending sentences with prepositions. Obeying these rules can often make language clearer but, in some cases, they make language more complicated. In that case, feel free to ignore them.
Clicka button in a graphical user interface using a mouse. Do not
Pressa key or key combination on a keyboard.
Typewords or numbers using a keyboard.
deselectan item in a menu.
Navigateto a page or location in a graphical user interface.
Adverbs : Do not use.
👍 Install TimescaleDB.
❌ Simply install TimescaleDB.
And/Or : Do not use. You can usually pick one. If you're not sure, pick "and."
❌ I like apples and/or oranges.
👍 I like apples and oranges.
Contractions : Absolutely fine to use, but try not to overdo it.
File system : Two words.
Latin abbreviations : Do not use.
👍 For example
Next : Avoid all directional words. You cannot guarantee that things will stay in the same position, or be in the position you expect on an individual reader's device.
Previous : Avoid all directional words. You cannot guarantee that things will stay in the same position, or be in the position you expect on an individual reader's device.
Promscale Connector : Use initial capital letters.
👍 "Install the Promscale Connector."
❌ "Install the Promscale connector."
❌ "Install the promscale connector."
Thus : Do not use.
Timescale : The name of the company. Do not use camel case.
👍 Timescale is hosting a virtual event.
❌ I have installed Timescale to manage my time-series data.
TimescaleDB : The name of the product. Capitalize the initial letter, and the "DB" at the end.
👍 "I have installed TimescaleDB to manage my time-series data."
❌ "TimescaleDB is hosting a virtual event."
❌ "I want to install TimeScaleDB"
Update : An update is a small or minor improvement, often delivered in a patch. Updates are done frequently, and require little or no downtime.
👍 Install the security update to patch this version.
Upgrade : An upgrade is a large or major improvement, and usually requires a new version. Upgrades are done less frequently, and could require planning, prepatory backups, and planned downtime.
👍 Upgrade from TimescaleDB 1 to TimescaleDB 2.
👍 Upgrade from TimescaleDB 2.3 to TimescaleDB 2.4.
Utilize : Do not use. Use "use" instead.
Via : Avoid if possible. There is usually a more accurate English word, like "through," "with," or "using."
Will : Do not use. It usually indicates that you are writing in future tense. Always write in simple present tense.
👍 After installation, you see a message.
❌ After installation, you will see a message.
Found an issue on this page?Report an issue!