Is there a "Writers Guide" for Fedora docs?

We used to have a kind of “writer’s Guide” containing phrasing guidelines (e.g. no/low indirect sentences), formatting guidelines (e.g. no capitalization in titles), design and layout options (e.g. aside boxes) and macros for recurring elements. This would be something like an extended tool set.

Do we still have something like that somewhere? I haven’t found anything on the docs pages.

2 Likes

I take this as an onboarding guide on git workflow, but can’t find anything about the style guide.
Quite daunting how to contribute in Docs.

Do we still have something like that somewhere?

I find these useful for me to be self-sufficient. I’m getting hands-on with git workflow. It will take some time for me to contribute.

  1. Developer portal: writing guide
    Fedora Developer Portal Project

  2. Fedora Magazine: good onboarding guide, which I can follow step by step When I’m stuck, I reach out to editors for advice.
    Tips for article style, grammar, content, and SEO :: Fedora Docs

On another note, it was nice to find you in Docs meeting the other day.

The only guide we have is the technical one linked above. A style guide would be a nice addition to that.

1 Like

A style guide would be nice. For the package maintainers docs, the one thing we’ve tried to stick to is Semantic Line Breaks.

https://pagure.io/fedora-docs/package-maintainer-docs/blob/main/f/README.md

Also I think such guide would be good for the docs.
It would be much nicer to read docs.fp.o if all the docs has consistent style.
Fedora Magazine’s guide looks good
(though I disagree with the “no inline monospace” rule).

Some other things I would like to see in such guide:

  • Casing for acronyms: is it json or JSON?
  • What to put in anchor text for links?
    I find it much clearer when the title of the linked page or section is preferred.
  • How to indicate placeholders for commands and code the reader should type into their system. If the reader is expected to change directory, is it cd MYPATH, cd <mypath> or something else?

+1 for semantic linebreaks from me.
They make tracking changes so much easier,
and at least for me, even improve text structure,
because I end up writing cleaner sentences when I apply them.
With Pagure’s diff viewer, applying line breaks somewhere is a must,
single line paragraphs are simply not reviewable with that tool.

2 Likes

Another item that came up recently: How page attributes should be used.
It seems that with the new ui bundle, :toc: should never be used (package-maintainer-docs#68).
I have seen some pages uses :experimental:, but I do not know what it does.
Then in some repositories there is file partials/attributes.adoc
with attributes like :year:, :PREVIOUSOSVER:, :MAJOSOSVER:.
Giving guidance how to properly all of these would be useful.

Should this topic now be split into a new one with the original question’s answer being no? The new topic could be based on the conversation that is developing around the details of creating the style guide.
As a Fedora Magazine editor, I liked the magazines style guide fairly well. I would suggest to get the design team involved (unless of course you already did) if the intention is to have a uniformity across the documentation realm of Fedora. A generic “Writers Style Guide” would help in any case, it could be referenced by any doc project.

1 Like

I opened an issue in the repo for this. I don’t mind doing this, but I won’t have a chance to get to it for a week or so. If someone beats me to it, that’s fine.

4 Likes

Agreed, and thankfully bcotton opened an (yet another) issue. I’m still lost in all that open issues and discussion threads. So, in addition we need work organization. Probably, we can use pagure milestones to bring all the issues into a prioritized order and timeline.

1 Like