Comments (6)
Short or long headers aren't a problem. Too short or too long is. Question is, what makes it 'too'. You're right that it's very much a case by case thing.
from foreman-documentation.
@apinnick You give good examples of headings that are probably overly specific and, as a result, too long. For example:
Configuring Smart Proxy server with default SSL certificates for load balancing without Puppet
To give examples of headings that are not specific enough (these are currently used in the installation guide):
5.1. Using LDAP
5.2. Using FreeIPA
5.3. Using Active Directory
The issue with overly specific headings is that they are too long. The issue with headings that are not specific enough is that they are misleading (5.2. Using FreeIPA doesn't describe using FreeIPA; it describes how to connect Satellite to FreeIPA to use it as an external authentication source).
Following the 3-11 word limit for headings might help us strike the right balance between these two issues. But it might also lead to minor inconsistencies (while one scenario might be described in 3-11 words including things like for {Project}
, another might only fit the 11 word limit without for {Project}
).
from foreman-documentation.
@asteflova I think shorter, more focused guides are the answer to the "not specific enough" header problem. If you have an (External) Authentication guide then "Using LDAP" is not so ambiguous anymore.
The more I think about it, the more I end up leaning to splitting up the Installation guide. Instead start with a basic Installation guide and then for every concept (Authentication, SCAP, Puppet, Provisioning, DNS, DHCP, ...) have separate guides that have their own installation section(s).
from foreman-documentation.
This might be useful for reaching a consensus: The RH-SSG guide requires writers to keep headings between 3 to 11 words:
Use clear titles with familiar keywords for customers. Keep titles and headings between 3 to 11 words. Headings that are too short lack clarity and don’t help customers know what’s in a section. Headings that are too long are less visible in Google searches and harder for customers to understand.
from foreman-documentation.
@apinnick
The issue with overly specific headings is that they are too long. The issue with headings that are not specific enough is that they are misleading (5.2. Using FreeIPA doesn't describe using FreeIPA; it describes how to connect Satellite to FreeIPA to use it as an external authentication source).
Maybe I should rename this issue, "Make headers better" :-)
If I had to choose my battles, I would start with headers that are too long, mainly because they are so annoying.
Headers that are too short are less problematic, in my experience, because usually there is enough context (the document itself or an intro paragraph) for the reader to figure out what it means.
from foreman-documentation.
Headers that are too short are less problematic, in my experience, because usually there is enough context (the document itself or an intro paragraph) for the reader to figure out what it means.
Short headings that are not specific enough are also regularly pointed out in d/s peer reviews (crowdsourced minimalism sessions, RHEL editorial reviews, regular peer reviews too -- although there it depends on the peer reviewer).
So yes, the guide in which a section with a short heading is located provides enough context. But also, the style guidelines we're following and the advice we're getting from experienced people through the initiatives mentioned above indicate that short headings are not what we're expected to use.
I think the RH-SSG guide I linked earlier provides reasonable advice that we can apply on a case-by-case basis:
Principle 3: Titles and headings
Use clear titles with familiar keywords for customers. Keep titles and headings between 3 to 11 words. Headings that are too short lack clarity and don’t help customers know what’s in a section. Headings that are too long are less visible in Google searches and harder for customers to understand.
I know that if I, personally, start following it, it'll help me avoid writing long headings that led to the creation of this issue 🙃 while also allowing me to continually fix headings that are too short.
from foreman-documentation.
Related Issues (20)
- Add warning about EPEL not being supported in the repo setup section of install/update guides
- Planning for {Project} Guide - Content Sources terminology
- should we drop 'Content hosts'? HOT 3
- friendly reminder: do not forget to cherry-pick to 3.10! HOT 3
- Reword "internal Smart Proxy" and "external Smart Proxy" HOT 1
- Restructure branches into web and guides (nightly, X.Y, etc) HOT 4
- Decide on foreman-installer "--option=true" vs --option true" HOT 4
- Re-document katello-pull-transport-migrate
- Check if "Content Host" needs to be removed from Prereqs too HOT 7
- Add hint about default Puppet Environment HOT 2
- Fix version details - RHEL7 to RHEL8 on Satellite v6.12 - v6.15 in performance tuning doc HOT 1
- Removal of {context} from IDs HOT 1
- Introduce a Foreman & DNS guide HOT 9
- Shortened guide titles need link updates in code for Sat
- Idea: Document how to mirror Ubuntu Pro packages? HOT 7
- Move "use tmux because the upgrade takes a very long time" to snippet
- Relocate and rewrite deleted note about CVs
- Update link to "Configuring LDAP as an ext auth" in Satellite web UI
- Improve introduction in guides/common/modules/con_performing-additional-configuration-on-smart-proxy-server.adoc
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from foreman-documentation.