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)
- 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
- Further improvements to the Discovery chapter in provisioning HOT 1
- Clean up docs around required plug-ins HOT 1
- Realm procedure has redundant steps HOT 3
- Reword "run this command" to something meaningful
- Change "Ansible playbook" to "Ansible Playbook"
- Planning for deprecated documentation (was "Remove deprecated") HOT 13
- Capitalize "remote execution" or not? HOT 7
- Usage of "X using Y" versus "do X by using Y" HOT 5
- Use "product" instead of "Product" HOT 3
- Improve review labels for PRs HOT 8
- Create docs around Use custom pre/post snippets for errata templates HOT 3
- Linkchecker very slow, often times out HOT 3
- Move content overrides to Managing hosts
- Reword snippet to run custom code before/after host provisioning
- Consolidate and update "Contributing" docs (in progress)
- Review contribution guidelines for cherry-picking
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.