Skip to content

Commit 366f2ec

Browse files
abhatt-rhabhatt-rh
authored
Merge pull request redhat-edge-computing#3 from abhatt-rh/td-801
TELCODOCS-801: Add the Contribution Guide and related files and folder
2 parents b0722e6 + d2d0d18 commit 366f2ec

File tree

4 files changed

+350
-0
lines changed

4 files changed

+350
-0
lines changed

‎content/contribute/contribute-to-docs.adoc

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
layout: default
3+
title: Contributor's guide
4+
menu: contribute
5+
weight: 60
6+
---
7+
8+
:toc:
9+
10+
Use the Contributor's guide to learn about ways to contribute to the Hybrid Cloud Patterns, to understand the prerequisites and toolchain required for contribution, and to follow some basic documentation style and structure guidelines.
11+
12+
include::modules/contributing.adoc[leveloffset=+1]
13+
include::modules/tools_and_setup.adoc[leveloffset=+1]
14+
include::modules/doc_guidelines.adoc[leveloffset=+1]

‎modules/contributing.adoc

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
[id="contributing-to-docs-contributing"]
2+
= Contribute to Hybrid Cloud Patterns documentation
3+
:icons:
4+
:description: Contribute to Hybrid Cloud Patterns documentation
5+
:imagesdir: ../images
6+
7+
8+
== Different ways to contribute
9+
10+
There are a few different ways you can contribute to Hybrid Cloud Patterns documentation:
11+
12+
* Email the Hybrid Cloud Patterns team at `<>@redhat.com`.
13+
* Create a link:https://github.com/hybrid-cloud-patterns/docs/issues[GitHub] or link:https://issues.redhat.com/projects/MBP/issues[Jira issue] .
14+
//to-do: Add link to the contribution workflow when we have a proper one. You might need to create a new file
15+
* Submit a pull request (PR). To create a PR, create a local clone of your own fork of the link:https://github.com/hybrid-cloud-patterns/docs[Hybrid Cloud Patterns docs repository], make your changes, and submit a PR. This option is best if you have substantial changes. For more details on creating a PR see <topic_link_to_contribution_workflow>.
16+
17+
== Contribution workflow
18+
// to-do:Create a docs team: https://github.com/orgs/hybrid-cloud-patterns/teams
19+
When you submit a PR, the https://github.com/orgs/hybrid-cloud-patterns/teams/docs[Hybrid Cloud Patterns Docs team] reviews the PR and arranges further reviews by Quality Engineering (QE), subject matter experts (SMEs), and others, as required. If the PR requires changes, updates, or corrections, the reviewers add comments in the PR. The documentation team merges the PR after you have implemented all feedback, and you have squashed all commits.
20+
21+
22+
== Repository organization
23+
24+
//to-do:Placeholder to explain how assemblies, modules, images, common/attribute folders are organized.
25+
26+
----
27+
├── assemblies
28+
│ └── multicloud-gitops-architecture.adoc
29+
├── modules
30+
│ └── multicloud-gitops-logical-architecture.adoc
31+
│ └── multicloud-gitops-physical-architecture.adoc
32+
├── common-attributes
33+
│ └── common_attributes.adoc
34+
├── snippets
35+
│ └── common-snippets.adoc
36+
├── images
37+
│ └── hybrid-multicloud-management-gitops-hl-arch.png
38+
└── README.adoc
39+
40+
----
41+
42+
== Next steps
43+
* link:tools_and_setup.adoc[Install and set up the tools and software]
44+
on your workstation so that you can contribute.
45+
* link:doc_guidelines.adoc[Review the documentation guidelines] to
46+
understand some basic guidelines to keep things consistent
47+
across our content.

‎modules/doc_guidelines.adoc

+218
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
[id="contributing-to-docs-doc-guidelines"]
2+
= Documentation guidelines
3+
4+
:description: Documentation guidelines for contributing to the Hybrid Cloud Patterns Docs
5+
:imagesdir: ../images
6+
7+
== General guidelines
8+
When authoring content, follow these style guides:
9+
10+
* link:https://redhat-documentation.github.io/supplementary-style-guide/[Red Hat Supplementary Style Guide]
11+
* link:https://www.ibm.com/docs/en/ibm-style[IBM Style], especially link:https://www.ibm.com/docs/en/ibm-style?topic=word-usage[word usage]
12+
+
13+
NOTE: When asked for an IBMid, Red Hat associates can use their Red Hat e-mail.
14+
* link:https://redhat-documentation.github.io/modular-docs/#writing-mod-docs[Modular documentation reference guide]
15+
** link:https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files[Modular documentation templates]
16+
17+
== Modular documentation terms
18+
19+
[options="header"]
20+
|===
21+
22+
|Modular doc entity |Description
23+
24+
|Asssembly
25+
|An _assembly_ is a collection of modules that describes how to accomplish a user story.
26+
27+
|Concept module
28+
|A _concept_ contains information to support the tasks that users want to do and must not include task information like commands or numbered steps. In most cases, create your concepts as individual modules and include them in appropriate assemblies. Avoid using gerunds in concept titles. "About <concept>" is a common concept module title.
29+
30+
|Procedure module
31+
|A procedure contains the steps that users follow to complete a process or task. Procedures contain ordered steps and explicit commands. In most cases, create your procedures as individual modules and include them in appropriate assemblies. Use a gerund in the procedure title, such as "Creating".
32+
33+
|Reference module
34+
|A reference module provides data that users might want to look up, but do not need to remember. A reference module has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want.
35+
36+
|===
37+
38+
39+
== Naming conventions for assembly and module files
40+
Use lowercase separated by dash. Create assembly and module file names that accurately and closely reflect the title of the assembly or module.
41+
42+
.Examples
43+
* `designing-guided-decision-tables.adoc` (Assembly of guided decision table modules)
44+
* `guided-decision-tables.adoc` (Concept module)
45+
* `creating-guided-decision-tables.adoc`` (Procedure module for creating)
46+
* `guided-decision-table-examples.adoc` (Reference module with examples)
47+
48+
=== Content type attributes
49+
50+
Each `.adoc` file must contain a `:_content-type:` attribute in its metadata that indicates its file type. This information is used by some publication processes to sort and label files.
51+
52+
Add the attribute from the following list that corresponds to your file type:
53+
54+
* `:_content-type: ASSEMBLY`
55+
* `:_content-type: CONCEPT`
56+
* `:_content-type: PROCEDURE`
57+
* `:_content-type: REFERENCE`
58+
59+
See, xref:doc_guidelines.adoc#assembly-file-metadata[Assembly file metadata] and xref:doc_guidelines.adoc#module-file-metadata[Module file metadata].
60+
61+
== Naming conventions for directories
62+
63+
Use lowercase. For directory with a multiple-word name, use lowercase separated by dash, for example `multicloud-gitops`.
64+
65+
== Language and grammar
66+
Consider the following guidelines:
67+
* Use present tense.
68+
* Use active voice.
69+
* Use second person perspective (you).
70+
* Avoid first person perspective (I, we, us).
71+
* Be gender neutral.
72+
* Use the appropriate tone.
73+
* Write for a global audience.
74+
75+
== Titles and headings
76+
Use sentence-style capitalization in all titles and section headings. Ensure that titles focus on customer tasks instead of the product.
77+
78+
For assemblies and procedure modules, use a gerund form in headings, such as:
79+
80+
* Creating
81+
* Managing
82+
* Using
83+
84+
For modules that do not include any procedure, use a noun phrase, for example _Red Hat Process Automation Manager API reference_.
85+
86+
//=== Discrete headings (commenting out for now. might need it later)
87+
88+
//If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
89+
90+
//http://asciidoctor.org/docs/user-manual/#discrete-or-floating-section-titles
91+
92+
//A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason).
93+
94+
//To use a discrete heading, just add `[discrete]` to the line before your unique ID. For example:
95+
96+
//----
97+
//[discrete]
98+
//[id="managing-authorization-policies_{context}"]
99+
//== Managing authorization policies
100+
//----
101+
102+
== Writing assemblies
103+
104+
For more information about forming assemblies, see the
105+
link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template].
106+
107+
[id="assembly-file-metadata"]
108+
=== Assembly file metadata
109+
Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
110+
111+
----
112+
:_content-type: ASSEMBLY <1>
113+
[id="<unique-heading-for-assembly>"] <2>
114+
= Assembly title <3>
115+
include::_common-docs/common-attributes.adoc[] <4>
116+
:context: <unique-context-for-assembly> <5>
117+
<6>
118+
:toc: <7>
119+
----
120+
121+
<1> The content type for the file. For assemblies, always use `:_content-type: ASSEMBLY`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
122+
<2> A unique anchor ID for this assembly. Use lowercase. Example: cli-developer-commands
123+
<3> Human readable title (notice the '=' top-level header)
124+
<4> Includes attributes common to Hybrid Cloud Patterns docs.
125+
<5> Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
126+
<6> A blank line. You *must* have a blank line here before the toc.
127+
<7> The table of contents for the current assembly.
128+
129+
After the heading block and a single whitespace line, you can include any content for this assembly.
130+
131+
132+
== Writing modules
133+
For more information about creating modules, see the https://redhat-documentation.github.io/modular-docs/#_creating_modules[Red Hat Modular documentation reference guide].
134+
135+
[id="module-file-metadata"]
136+
=== Module file metadata
137+
Every module should be placed in the modules folder and should contain the following metadata at the top:
138+
139+
----
140+
// * list of assemblies where this module is included <1>
141+
142+
:_content-type: <TYPE> <2>
143+
[id="<module-anchor>_{context}"] <3>
144+
= Module title <4>
145+
----
146+
147+
<1> The content type for the file. Replace `<TYPE>` with the actual type of the module, `CONCEPT`, `REFERENCE`, or `PROCEDURE`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
148+
<2> List of assemblies in which this module is included.
149+
<3> A module anchor with {context} that must be lowercase and must match the module's file name. The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
150+
<4> Human readable title. To ensure consistency in the results of the
151+
leveloffset values in include statements, you must use a level one heading
152+
( = ) for the module title.
153+
154+
Example:
155+
156+
----
157+
// Module included in the following assemblies:
158+
//
159+
// * cli_reference/developer-cli-commands.adoc
160+
161+
:_content-type: REFERENCE
162+
[id="cli-basic-commands_{context}"]
163+
= Basic CLI commands
164+
----
165+
166+
[id="attribute-files"]
167+
== Attribute files
168+
169+
AsciiDoc attributes are variables you can use in common files to:
170+
171+
* avoid hard-coding brand-specific information,
172+
173+
* share content between multiple brands more easily.
174+
175+
All attribute files must be placed in the a separate attributes file. For example, `common-docs` directory.
176+
177+
It is acceptable to group related attributes in the `common-attributes.adoc` file under a comment, as shown in the following example:
178+
179+
----
180+
//ACM
181+
rh-rhacm-product: Red Hat Advanced Cluster Management (RHACM)
182+
:rh-shortname: RHACM
183+
//GitOps
184+
:gitops-product: Red Hat OpenShift GitOps
185+
:gitops-shortname: GitOps
186+
----
187+
188+
For more information on attributes, see link: https://docs.asciidoctor.org/asciidoc/latest/key-concepts/#attributes.
189+
190+
== Formatting
191+
Use the following links to refer to AsciiDoc markup and syntax.
192+
193+
* https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Red Hat Documentation]
194+
195+
* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
196+
197+
If you are graduating to AsciiDoc from Markdown, see the https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/#comparison-by-example[AsciiDoc to Markdown syntax comparison by example].
198+
199+
=== Formatting commands and code blocks
200+
To enable syntax highlighting, use `[source,terminal]` for any terminal commands, such as `oc` commands and their outputs. For example:
201+
....
202+
[source,terminal]
203+
----
204+
$ oc get nodes
205+
----
206+
....
207+
208+
To enable syntax highlighting for a programming language, use `[source]` tags used in the code block. For example:
209+
210+
* `[source,yaml]`
211+
212+
* `[source,go]`
213+
214+
* `[source,javascript]`
215+
216+
217+
218+

‎modules/tools_and_setup.adoc

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
[id="contributing-to-docs-tools-and-setup"]
2+
= Install and set up the tools and software
3+
:icons:
4+
:linkattrs:
5+
:description: How to set up and install the tools to contribute
6+
7+
8+
== Create a GitHub account
9+
Before you can contribute to Hybrid Cloud Patterns documentation, you must
10+
https://www.github.com/join[sign up for a GitHub account].
11+
12+
== Set up authentication
13+
When you have your account set up, follow the instructions to
14+
https://help.github.com/articles/generating-ssh-keys/[generate and set up SSH
15+
keys on GitHub] for proper authentication between your workstation and GitHub.
16+
17+
Confirm authentication is working correctly with the following command:
18+
19+
----
20+
$ ssh -T [email protected]
21+
----
22+
23+
== Fork and clone the Hybrid Cloud Patterns documentation repository
24+
You must fork and set up the Hybrid Cloud Patterns documentation repository on your workstation so that you can create PRs and contribute. These steps must only be performed during initial setup.
25+
26+
. Fork the https://github.com/hybrid-cloud-patterns/docs repository into your
27+
GitHub account from the GitHub UI. Click *Fork* in the upper right-hand corner.
28+
29+
. In the terminal on your workstation, change into the directory where you want
30+
to clone the forked repository.
31+
32+
. Clone the forked repository onto your workstation with the following
33+
command, replacing _<user_name>_ with your actual GitHub username.
34+
+
35+
----
36+
$ git clone [email protected]:<user_name>/docs.git
37+
----
38+
39+
. Change into the directory for the local repository you just cloned.
40+
+
41+
----
42+
$ cd docs
43+
----
44+
45+
. Add an upstream pointer back to the Hybrid Cloud Patterns's remote repository, in this
46+
case _docs_.
47+
+
48+
----
49+
$ git remote add upstream [email protected]:hybrid-cloud-patterns/docs.git
50+
----
51+
52+
This ensures that you are tracking the remote repository to keep your local
53+
repository in sync with it.
54+
55+
== Install Asciidoctor
56+
The Hybrid Cloud Patterns documentation is created in AsciiDoc language, and is processed with http://asciidoctor.org/[AsciiDoctor], which is an AsciiDoc language processor.
57+
58+
=== Prerequisites
59+
The following are minimum requirements:
60+
61+
* A bash shell environment (Linux and OS X include a bash shell environment)
62+
* A web browser (Firefox, Chrome, or Safari)
63+
* https://docs.asciidoctor.org/asciidoctor/latest/tooling/#web-browser-add-ons-preview-only[Web browser add-ons (preview only)]??
64+
* An editor that can strip trailing whitespace
65+
* An https://docs.asciidoctor.org/asciidoctor/latest/install/[installer]
66+
67+
//to-do: Add instructions to "Install Hugo"
68+
69+
//to-do: Add instructions "Deploy Hugo as a container image"
70+
71+

0 commit comments

Comments
 (0)