search

StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 20 forks source link

Review book heading design #11

Open daobrien opened 8 years ago

daobrien commented 8 years ago

The Style Guide breaks some of its own rules wrt heading design and layout. e.g., some headings are immediately followed by other headings with no intervening text.

daobrien commented 5 years ago

Have patched a couple of these but more to do.

julian-cable commented 2 years ago

Suggest to expand the scope to include also matters of grammar and style throughout the guide that do not adhere to its own conventions.

daobrien commented 2 years ago

That would make this a very big issue, and I think we'd be better off focusing on specifics.

  1. Look at the headings. If they're nonstandard or otherwise "bad", fix them.
  2. Look at TOPIC_1, weed them all out and fix them.
  3. Continue... forever? :) It's a lot easier to get more ppl, especially community contributors, engaged if the issues are more manageable.
daobrien commented 1 year ago

@julian-cable I think this relates to a recent issue you opened so maybe decide which is more accurate and close the other.

julian-cable commented 1 year ago

The two issues do have a partial overlap, but their scope is different. This issue is focused purely on heading design. The scope of the other issue is much wider and involves reviewing all the content in the guide (not just headings) for conformity to our own guidance.

daobrien commented 1 year ago

Right, and I think something like "reviewing all the content" is too broad for a single issue. Better to focus on areas, deal with them, get them merged, and move on to the next. Otherwise you're going to have a very large, long-lived branch on your hands that could easily get in the way of addressing other issues. (67 open issues in the style guide right now.)

So, instead of closing the other one, just refine it?

julian-cable commented 1 year ago

That other issue is more of an early placeholder right now, as an aide memoire, to be implemented in a future release. When the time comes, I would expect to break it down into smaller tasks and maybe have a separate branch for each chapter. But that's for the future.