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 19 forks source link

Update section on lists #575

Open daobrien opened 1 month ago

daobrien commented 1 month ago

https://stylepedia.net/style/6.2/#Sentence_Structure-Using_Lists_Correctly

Some of the guidance and examples here are incorrect or misleading.

E.g., this example should use "Go to": 'Navigation or similar instructions (such as "Navigate to Menu -> Submenu").'

'Use a list with compact spacing in all other cases.'

There's no provision for how we treat 'Outcomes' section. Such sections are not unique to us, but they are fairly specific. We need something that provides for 'other sections where your deliverables might benefit from more spacing between list items' or similar.