Skip to content

Commit 8491118

Browse files
committed
reverting assembly metadata rules
1 parent e2bb931 commit 8491118

File tree

1 file changed

+11
-17
lines changed

1 file changed

+11
-17
lines changed

contributing_to_docs/doc_guidelines.adoc

Lines changed: 11 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,10 @@ Every assembly file must contain the following metadata at the top, with no blan
3939
:_mod-docs-content-type: ASSEMBLY <1>
4040
[id="<assembly-anchor-id>"] <2>
4141
= Assembly title <3>
42-
<4>
43-
include::_attributes/common-attributes.adoc[] <5>
42+
include::_attributes/common-attributes.adoc[] <4>
43+
:context: <assembly-context> <5>
4444
<6>
45-
:context: <assembly-context> <7>
46-
<8>
47-
toc::[] <9>
45+
toc::[] <7>
4846
----
4947
<1> The content type for the file. For assemblies, always use `:_mod-docs-content-type: ASSEMBLY`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
5048
<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase and hyphens, for example: `cli-developer-commands`.
@@ -58,8 +56,7 @@ toc::[] <9>
5856
* The assembly title, which is the first line of the document, is the only level 1 ( `=` ) title.
5957
Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminology), formatted as `==`. When you include modules, you must add leveloffsets in the include statements. You can manually add more H2 (`==`) section headers in the assembly.
6058
====
61-
<4> You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.
62-
<5> Includes attributes common to OpenShift docs.
59+
<4> Includes attributes common to OpenShift docs.
6360
+
6461
[NOTE]
6562
====
@@ -70,21 +67,18 @@ Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminolog
7067
----
7168
:_mod-docs-content-type: ASSEMBLY
7269
include::_attributes/common-attributes.adoc[]
73-
7470
[id="installing-ibm-cloud-private"]
7571
= Installing a private cluster on {ibm-cloud-title}
76-
7772
:context: installing-ibm-cloud-private
7873
7974
toc::[]
8075
----
8176
====
82-
<6> You must include a blank line after each `include::` statement.
83-
<7> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example `cli-developer-commands`.
84-
<8> A blank line. You *must* have a blank line here before the `toc::[]`.
77+
<5> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example `cli-developer-commands`.
78+
<6> A blank line. You *must* have a blank line here before the `toc::[]`.
8579
+
8680
After the heading block and a single whitespace line, you can include any content for this assembly.
87-
<9> The table of contents for the current assembly.
81+
<7> The table of contents for the current assembly.
8882

8983
[id="module-file-metadata"]
9084
== Module file metadata
@@ -950,12 +944,12 @@ IMPORTANT: You cannot link to a repository that is hosted on www.github.com. An
950944
TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link.
951945

952946
==== Guidance for including outside sources
953-
In general, avoid linking to sources outside of an official Red Hat domain whenever possible.
947+
In general, avoid linking to sources outside of an official Red Hat domain whenever possible.
954948

955-
Some acceptable exceptions to this rule include:
949+
Some acceptable exceptions to this rule include:
956950

957-
1. Links to third-party product documentation when it would be otherwise unreasonable or impossible to write procedures using another product.
958-
2. Upstream resources for a feature or component based on an upstream project when re-writing the resource for downstream use would be too arduous to write for too little value, or too difficult to maintain.
951+
1. Links to third-party product documentation when it would be otherwise unreasonable or impossible to write procedures using another product.
952+
2. Upstream resources for a feature or component based on an upstream project when re-writing the resource for downstream use would be too arduous to write for too little value, or too difficult to maintain.
959953
3. Upstream API references
960954

961955
If you feel you need to link to an outside source, discuss it with a content strategist, and then make sure you have approval from your PM and engineering stakeholders and the Product Operations team member who works in your area.

0 commit comments

Comments
 (0)