Comments (8)
The main reason for including the note is that some writers would put entire lists in bold for some reason. This is to prevent that.
I'm not sure what you mean by "titled steps in procedures"... Do you really give titles to individual items in ordered lists? I can't quite imagine how that looks like, but I would argue that if something is substantial enough to require a heading/title of its own, then perhaps it should not be formatted/marked up as a mere list item.
from asciidoc-markup-conventions.
Good question. I wouldn't do this for a list being used as a list; it's more in the case where a list is being used because there is no markup for a procedure.
Here's an example: https://access.redhat.com/documentation/en-us/red_hat_hyperconverged_infrastructure/1.0/html/deploying_red_hat_hyperconverged_infrastructure/task-config-rhgs-using-cockpit
The steps here aren't exactly complex, but they're also not 4-10 words per step. Bolding the first line does two things:
- Readers who just want to jog their memory can skim through and focus on the step titles.
- Readers who need the extra guidance in the step have a clear focus as to the underlying purpose of the action performed in the step.
Putting a whole list in bold is definitely not necessary, but I feel using bold text to emphasise the key action can help.
from asciidoc-markup-conventions.
I was a bit surprised to see the note in the AsciiDoc conventions too, but for a different reason. It seems to be a 'best practice' for documentation style thing rather than a markup thing. In the same spirit, one could also add notes about other best practices: avoiding procedures with more than two levels, avoiding procedures with more than 7 steps, ...
Pure markup guidelines tend to be very simple and unambiguous: you are documenting a command and need to know what markup to use. Or you are including an image and need to know whether you need to include a title or not.
Style guidelines (like whether to use bold or not and where) are often more ambiguous and include more gray areas, which Laura illustrates in her comment.
I think it would be best to limit the AsciiDoc conventions to markup guidelines, and leave the style guidelines to our style guides (the IBM style guide includes some recommendations on using highlighting, including bold text, although it doesn't address steps in procedures specifically).
from asciidoc-markup-conventions.
@asteflova, there's a persistent misunderstanding wrt the purpose of these guidelines. Their aim IS NOT to teach writers how to use adoc mark-up. There are other excellent resources for that. The aim IS to standardize the look of our docs. The fact that the look is directly dependent on mark-up used is incidental.
So,
It seems to be a 'best practice' for documentation style thing rather than a markup thing.
Exactly. These guidelines should probably really be named "Element style guidelines with a bonus: what adoc mark-up to use to achieve the desired look".
one could also add notes about other best practices: avoiding procedures with more than two levels, avoiding procedures with more than 7 steps, ...
Let's not confuse style as in look and style as in stylistics. These guidelines are about the former. Your example is about the latter.
you are documenting a command and need to know what markup to use
Yes, so that when the doc is rendered, all commands look the same.
leave the style guidelines to our style guides (the IBM style guide includes some recommendations on using highlighting, including bold text, although it doesn't address steps in procedures specifically)
Again, mixing style and style... Although, I admit, I had no idea the IBM Style Guide talked about looks. I'm pretty sure its recommendations in this area are not universally followed within CCS. Regardless, we now have our own set of recommendations for this area: these guidelines.
.........................
Anyway: The big fail here is the recurring misunderstanding about the purpose of these guidelines. Ideas on how to remedy the situation are welcome. Would a simple retitling help?
from asciidoc-markup-conventions.
@laubai, I guess I understand now what you mean. Except, the doc you link to doesn't use any bolding in the 'step titles'. Be that as it may, I think this is a special case and should be determined by the writer in question.
The note in the guidelines is intended to discourage wholesale bolding of list items (which I myself have not encountered, but other members of the team witnessed and thought it prudent to include a note about it).
from asciidoc-markup-conventions.
The big fail here is the recurring misunderstanding about the purpose of these guidelines. Ideas on how to remedy the situation are welcome. Would a simple retitling help?
We should add an intro paragraph. => #14
from asciidoc-markup-conventions.
@laubai I'm not sure that I see bolded steps in the example doc that you shared. That looks totally fine to me. The only things I see bolded are GUI items, which is our recommendation for GUI items.
Below is an example of an old EAP doc that bolds the entire first sentence of a step. That is what we're saying not to do. Having a concise first sentence of a step on its own line, and the rest of the details in paragraphs, etc. below it should be sufficient. Though I've also seen instances where the first sentence of a step was bolded and it was in a giant paragraph and that is not good either.
from asciidoc-markup-conventions.
I totally agree with @laubai about marking a few words at the beginning of steps in bold, to emphasize key actions. I've had discussions with other writers in Red Hat who like this approach as well.
from asciidoc-markup-conventions.
Related Issues (20)
- Add supported syntax highlighting formats HOT 2
- Add links to AsciiDoc(tor) user manual and mark-up reference HOT 1
- Add intro paragraph HOT 2
- Edit text to say 'Click' instead of 'Press' HOT 1
- Mark the conventions that are experimental HOT 3
- Add 'Inline Icons' to this list
- Fix link to mod docs guide
- nbsp for product names HOT 4
- Use of Italics for "System or software variable to be replaced by the user" HOT 8
- Product name
- the subtitle is not accurate HOT 2
- Incorrect example of emphasis for a term HOT 3
- Keyboard shortcut example doesn't match IBM Style HOT 1
- Double underscore for italics surrounded by chevrons (aka pointy brackets)
- {nbsp} in Command Block HOT 1
- Needs to be more robust HOT 5
- Update the 'Reference to Red Hat guides' example HOT 1
- Update the 'System or software variable to be replaced by the user' example ad markup used HOT 1
- Update the 'Anchor' example HOT 3
- Add context description to clarify purpose of this resource
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 asciidoc-markup-conventions.