Codeberg/Documentation
42
199
Fork
You've already forked Documentation
161

Style Guide #223

Merged
fnetX merged 12 commits from ka2in/Documentation:branch2 into main 2022年05月17日 19:03:19 +02:00
Contributor
Copy link
No description provided.
Contributor
Copy link

The proposed style guide is a starting point. Feel free to adjust, extend, and modify according to the community's needs.

@ka2in: That is a great remark. Should we add it to the start of the document?

Maybe slightly adapted like:
"The proposed style guide is a starting point. Feel free to create an issue, open a Pull Request, and modify it according to the community's needs."

> The proposed style guide is a starting point. Feel free to adjust, extend, and modify according to the community's needs. @ka2in: That is a great remark. Should we add it to the start of the document? Maybe slightly adapted like: "The proposed style guide is a starting point. Feel free to create an issue, open a Pull Request, and modify it according to the community's needs."
Author
Contributor
Copy link

@jklippel I've added a corresponding Note at the beginning of the document.

@jklippel I've added a corresponding [Note](https://codeberg.org/Codeberg/Documentation/commit/d6f775fe2ba4e7fa6998fece96b5a4633d879dbb) at the beginning of the document.
fnetX left a comment
Copy link

Sorry for the late review, and thank you very much.

TBH, I think we should try to point out that you should still try to contribute to the docs, even if you don't know if you can fully fulfill the styleguide. This is kinda overwhelming when you "just wanted to write some sentences about x", and might turn off potential contributors.

Sorry for the late review, and thank you very much. TBH, I think we should try to point out that you should still try to contribute to the docs, even if you don't know if you can fully fulfill the styleguide. This is kinda overwhelming when you "just wanted to write some sentences about x", and might turn off potential contributors.
@ -0,0 +81,4 @@
Use the following format for dates in running text: **dd MMMM yyyy**, e.g. 15 March 2022.
Use the following "short" format for dates outside the running text: **dd.mm.yyyy**, e.g. 9.3.2022.
Owner
Copy link

I propose to use the same example date

I propose to use the same example date
Author
Contributor
Copy link

Done.

Done.
@ -0,0 +104,4 @@
|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| 6.20 p.m | 18.20 |
| 12 | 12.00 |
| 09.03.2022 | 9.3.2022 |
Owner
Copy link

Since this is repetitive, maybe merge the two sections (Time and date) with the no-leading-zero section

Since this is repetitive, maybe merge the two sections (Time and date) with the no-leading-zero section
Author
Contributor
Copy link

Done.

Done.
@ -0,0 +145,4 @@
## Document structure
If you write an excessively long article, your readers might get lost on the way. Break your article down in smaller parts for a better reading experience.
Owner
Copy link

Just for clarification: Does that mean to add more subheadings in the article itself, or create multiple articles?

Just for clarification: Does that mean to add more subheadings in the article itself, or create multiple articles?
Author
Contributor
Copy link

I mean breaking the article down into smaller articles, and readjusting the document structure, not only adding more subheadings.

I mean breaking the article down into smaller articles, and readjusting the document structure, not only adding more subheadings.
Author
Contributor
Copy link

@fnetX:

Thank you for reviewing the PR!

A style guide is meant to be used as a reference when there's a doubt about something specific. It's not a novel that we must read from A to Z.

If somebody comes here and wants to know how to format date and numbers, he can check the relevant section immediately. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.

In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.

@fnetX: Thank you for reviewing the PR! A style guide is meant to be used as a reference when there's a doubt about something specific. It's not a novel that we must read from A to Z. If somebody comes here and wants to know how to format date and numbers, he can check the relevant section immediately. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects. In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.
Contributor
Copy link

A style guide is meant to be used as a reference when there's a doubt about something specific. It's not a novel that we must read from A to Z.

If somebody comes here and wants to know how to format date and numbers, he can check the relevant section immediately. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.

In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.

Great explanation. Would you mind adapting it a little to be more generic and then adding it to the introduction?

> A style guide is meant to be used as a reference when there's a doubt about something specific. It's not a novel that we must read from A to Z. > > If somebody comes here and wants to know how to format date and numbers, he can check the relevant section immediately. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects. > > In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide. Great explanation. Would you mind adapting it a little to be more generic and then adding it to the introduction?
Author
Contributor
Copy link

@jklippel

Explanation added to the introduction.

@jklippel Explanation added to the introduction.
fnetX referenced this pull request from a commit 2022年05月17日 19:03:19 +02:00
Owner
Copy link

This was open for quite a while and all review remarks addressed as far as I could see.

This was open for quite a while and all review remarks addressed as far as I could see.
Owner
Copy link

Thank you @ka2in

Thank you @ka2in
Sign in to join this conversation.
No reviewers
Labels
Clear labels
Codeberg Pages
Issues affecting Codeberg Pages
Documentation Usability
Issues related to using and reading docs.codeberg.org
Forgejo
Good First Issue! 👋
Kind: Bug
Kind: Documentation
Kind: Enhancement
Kind: Feature
Kind: Question
Kind: Security
Licensing
Part: Generator
This is related to the generation of the documentation, not to the content itself
Priority: High
The priority is high
Priority: Low
The priority is low
Priority: Medium
The priority is medium
Reviewed: Confirmed
Something has been confirmed
Reviewed: Duplicate
Something exists already
Reviewed: Invalid
Something was marked as invalid
Reviewed: Wontfix
Something won't be fixed
Status: Blocked
Status: Help wanted
Contributions are welcome!
Status: In progress
Work is in progress
Status: Needs feedback
Feedback is needed
Status: Ready for Review
Work is completed
Status: Review
Review is in progress / Reviewers wanted
Status: Stale
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Codeberg/Documentation!223
Reference in a new issue
Codeberg/Documentation
No description provided.
Delete branch "ka2in/Documentation:branch2"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?