You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contributing_to_docs/doc_guidelines.adoc
+11-17Lines changed: 11 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,12 +39,10 @@ Every assembly file must contain the following metadata at the top, with no blan
39
39
:_mod-docs-content-type: ASSEMBLY <1>
40
40
[id="<assembly-anchor-id>"] <2>
41
41
= Assembly title <3>
42
-
<4>
43
-
include::_attributes/common-attributes.adoc[] <5>
42
+
include::_attributes/common-attributes.adoc[] <4>
43
+
:context: <assembly-context> <5>
44
44
<6>
45
-
:context: <assembly-context> <7>
46
-
<8>
47
-
toc::[] <9>
45
+
toc::[] <7>
48
46
----
49
47
<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.
50
48
<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>
58
56
* The assembly title, which is the first line of the document, is the only level 1 ( `=` ) title.
59
57
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.
60
58
====
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.
63
60
+
64
61
[NOTE]
65
62
====
@@ -70,21 +67,18 @@ Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminolog
70
67
----
71
68
:_mod-docs-content-type: ASSEMBLY
72
69
include::_attributes/common-attributes.adoc[]
73
-
74
70
[id="installing-ibm-cloud-private"]
75
71
= Installing a private cluster on {ibm-cloud-title}
76
-
77
72
:context: installing-ibm-cloud-private
78
73
79
74
toc::[]
80
75
----
81
76
====
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::[]`.
85
79
+
86
80
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.
88
82
89
83
[id="module-file-metadata"]
90
84
== Module file metadata
@@ -950,12 +944,12 @@ IMPORTANT: You cannot link to a repository that is hosted on www.github.com. An
950
944
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.
951
945
952
946
==== 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.
954
948
955
-
Some acceptable exceptions to this rule include:
949
+
Some acceptable exceptions to this rule include:
956
950
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.
959
953
3. Upstream API references
960
954
961
955
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