search

getsolus / help-center-docs

Solus's Help Center documentation as well as previous User Guide.
https://help.getsol.us
GNU General Public License v2.0
57 stars 83 forks source link

Add a style guide #426

Closed davidjharder closed 10 months ago

davidjharder commented 1 year ago

This is a draft for now. Open for comments

Fixes https://github.com/getsolus/help-center-docs/issues/391

deoxys94 commented 1 year ago

Hi @davidjharder,

I already left some comments in the file. Here are some other comments regarding your previous message in the original issue:

Short forms: PRs, dev, repo, etc. and other latin

I think Google already provides good guidance for that (In general, it's better to spell everything out unless it's a well-known term. For example: FBI).

When it comes to Latin abbreviations, never use them. They are difficult to understand (especially for ESL speakers) and difficult to translate. The only exception is etcetera, but it also has some specific "rules".

davidjharder commented 1 year ago

Hey @deoxys94, I don't see any in-line comments.

You're right, Google has well developed rules for the latin phrases that boil down to "don't"

deoxys94 commented 1 year ago

Hi @davidjharder. How about now? I think it should be visible.

You're right, Google has well developed rules for the latin phrases that boil down to "don't"

In general, simple English is the preferred choice for writing technical documentation. Google already has good guidelines for simple English. Here's another great resource for it: https://www.plainlanguage.gov/guidelines/

davidjharder commented 11 months ago

Hey deoxys94, I agree with most of your suggestions, thanks for the review. Sorry I took so long to get to it; I took a bit of a break.