Fedora Documentation Style Guide 1st draft proposal

I had some spare time this afternoon. And before wasting time in front of the TV, I did some research on our style guide. I looked at the Fedora magazine style guide we had discussed as a possible template, gathered some more recommendations I had developed myself in the course of my publishing work, and mixed it all together into a rough first draft.

I didn’t want to use hackmd.io again because the formatting is quite different. Instead, I put the text in our Contribution section without including it in the navigation. So it is not accessible via public links. But you can read the draft

Maybe we can gather feedback here and make a decision at the next meeting.


How about including conversational style?
Due to differences in style among the Magazine, Quick Docs and Docs, we need to adjust the tone to fairly conversational for an audience of new users or least conversational for experienced users

Example: Less conversational style
Docs (like Server Documentation)

Where does Quick Docs fit in? I’d think it is fairly conversational criteria. In spite of being ‘quick’, Quick Docs needs to explain the instructions easier to follow through. It does not necessarily verbose for the sake of being more explanatory.

Good idea, yes! It’s a great way to break a complex and broad subject area into smaller parts while focusing the reader’s attention on a specific topic.

Hey @pboy!

Should we also include admonitions guidelines in the style guide as well?

I had conducted a poll for the same- Classification of all the content on the docs website (Contribute if you can!) - #35 by likeanushkaa

Hi @likeanushkaa! Good to hear / read from you. Yes, we should. In my 1st draft, I just couldn’t find our discussions about it in a hurry. And I trusted you to get back to us when you saw the draft. :slight_smile:

By the way, I would like to have the combination of Tip, Important, Warning. But I think Tip and Note are functional equivalent. Or maybe green for notes? That might look more like “positive” and stand out more from all the blue on our pages. But maybe it doesn’t fit our color scheme design-wise?

And probably you might fill in your additional ideas? As it looks, we will soon have a development branch for the pages, and then we can work with PRs as usual.

1 Like

Initially I went with a green fir the notes, but the green that is a part of the Fedora design system isn’t so subtle to look at😅