Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Style guide #76

Open
mark-wiemer opened this issue Dec 19, 2024 · 3 comments
Open

Style guide #76

mark-wiemer opened this issue Dec 19, 2024 · 3 comments
Labels
Formatting Layout and formatting alterations Meta Related to project structure or procedures

Comments

@mark-wiemer
Copy link
Contributor

Aside from the technicalities of how to contribute, we should clarify the style of the docs site. For example, do we use Sentence case headings or Title Case Headings? This will be an iterative process, but it's something we should start early to get the docs looking professional and helping folks navigate the site and lower cognitive load.

@appgurueu
Copy link
Contributor

I don't think it matters much, the style is consistent enough currently I think (e.g. sentence case is pretty prevalent for titles, # is used for headings, * for list items).

Note also that having to follow style guides - assuming they wouldn't be automatically applied - increases the cognitive load for editors and reviewers.

@mark-wiemer
Copy link
Contributor Author

The adage goes "docs are read 100x more than they're written", I'm OK with a bit of cognitive load on doc writers, and I do think we can automatically enforce a good chunk of any style guide :)

Also note that most headings are currently Title Case, not sentence case, at least from what I've seen. Not a big deal to me but important to clarify in this discussion

@JosiahWI
Copy link
Contributor

JosiahWI commented Dec 20, 2024

Any style guides we have need to be enforced in CI where possible.

@GreenXenith GreenXenith added Meta Related to project structure or procedures Formatting Layout and formatting alterations labels Dec 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Formatting Layout and formatting alterations Meta Related to project structure or procedures
Projects
None yet
Development

No branches or pull requests

4 participants