docs/tickets

Create a "code style guide" for docs #44

New issue

Open

opened 2026-05-13 19:47:52 +00:00 by mwinters · 4 comments

mwinters commented

2026-05-13 19:47:52 +00:00

Member

Background

Our tooling is very flexible, with many different ways to accomplish the same things.

Some of the different ways to do things can have functional consequences, such as whether or not translations work: docs/quick-docs#967

Others are more about consistency, such as the syntax that we use for links, or when & where & how to use variables: council/docs#287

Suggestion

It would be great to have a documented set of Do's and Don'ts somewhere, and ensure that all docs repos reference it. These should ideally include "what", "why", and links to examples like I've provided here.

Perhaps this ticket could be used to track the list of things which should go into the style guide? If you feel this is already captured somewhere, feel free to close.

## Background Our tooling is very flexible, with many different ways to accomplish the same things. Some of the different ways to do things can have functional consequences, such as whether or not translations work: https://forge.fedoraproject.org/docs/quick-docs/pulls/967 Others are more about consistency, such as the syntax that we use for links, or when & where & how to use variables: https://forge.fedoraproject.org/council/docs/pulls/287 ## Suggestion It would be great to have a documented set of Do's and Don'ts somewhere, and ensure that all docs repos reference it. These should ideally include "what", "why", and links to examples like I've provided here. Perhaps this ticket could be used to track the list of things which should go into the style guide? If you feel this is already captured somewhere, feel free to close. ## Related issues - https://forge.fedoraproject.org/docs/tickets/issues/36 - https://forge.fedoraproject.org/docs/tickets/issues/18

mwinters commented

2026-05-13 19:48:44 +00:00

Author

Member

I'll add as a bonus: let's have a linter for these things!

And a bonus bonus: let's make the linter easy for people to integrate into Forge CI for docs repos!

I'll add as a bonus: let's have a linter for these things! And a bonus bonus: let's make the linter easy for people to integrate into Forge CI for docs repos!

👍 1

pbokoc added the

labels

2026-05-29 12:08:34 +00:00

pbokoc commented

2026-05-29 12:16:29 +00:00

Owner

Re: linter - see #9

Re: linter - see https://forge.fedoraproject.org/docs/tickets/issues/9

mwinters commented

2026-05-29 21:34:37 +00:00

Author

Member

@pbokoc wrote in #44 (comment):

Re: linter - see #9

Vale is for linting your prose -- passive voice, gerunds, that sort of thing.

I'm talking about syntax and structure: don't declare variables scoped to a single page, always use the same syntax to create links, etc. A quick search turns up https://github.com/docToolchain/asciidoc-linter/ but it looks like we'd have to write some custom rules for it. Not sure whether there are better alternatives.

@pbokoc wrote in https://forge.fedoraproject.org/docs/tickets/issues/44#issuecomment-778804: > Re: linter - see #9 Vale is for linting your prose -- passive voice, gerunds, that sort of thing. I'm talking about syntax and structure: don't declare variables scoped to a single page, always use the same syntax to create links, etc. A quick search turns up https://github.com/docToolchain/asciidoc-linter/ but it looks like we'd have to write some custom rules for it. Not sure whether there are better alternatives.

👍 1

pboy added this to the 2026 Q2 Team Goals milestone

2026-06-21 13:12:47 +00:00

pboy removed this from the 2026 Q2 Team Goals milestone

2026-06-21 13:12:57 +00:00

pboy commented

2026-06-28 16:53:42 +00:00

Owner

I think, on one hand we should include rules/hints like the examples above in our Style Guide. On the other hand we should include it in our QA/QI of automation efforts.

What are the next steps here?

I think, on one hand we should include rules/hints like the examples above in our Style Guide. On the other hand we should include it in our QA/QI of automation efforts. What are the next steps here?

pboy added the

Contributors' Guidance

Improve written Material

label

2026-06-28 17:30:10 +00:00