docs-cloudfoundry-concepts/contribute.html.md.erb at master · cloudfoundry/docs-cloudfoundry-concepts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
---
title: Contribute to Cloud Foundry documentation
owner: Docs
---

You can contribute to <%= vars.platform_name %> documentation.

The <%= vars.platform_name %> documentation relies on contributions from the community to remain accurate, complete, and consumable.

Reasons to contribute to the <%= vars.platform_name %> documentation are:

* You noticed that a topic is incorrect or incomplete.
* You are developing a new <%= vars.platform_name %> feature and want to tell users know how to use it.
* You want to help your fellow humans.
* You do not like the idea of someone else having to go through what you just went through to figure something out. Such a waste; so inefficient.


## <a id='contribute'></a> How can you contribute?

The source files for all <%= vars.platform_name %> documentation are hosted on [GitHub](http://github.com), and each documentation page has a link to its GitHub source file at the bottom. The source files are in Markdown/HTML/embedded Ruby (`html.md.erb`) format.

If you use GitHub, the most direct and effective way to contribute to the documentation is to submit a pull request (PR) or raise an issue in the GitHub repository containing the documentation that you want to change. For more information, see [Submit a GitHub Pull Request](#github-pr) and [Raise a GitHub Issue](#github-issue).

If you do not already use GitHub, you can contribute to the <%= vars.platform_name %> documentation in other ways. For more information, see [Contribute Without GitHub](#non-github).

Whichever way you contribute, please follow the guidelines in [Advice for Contributors](#advice).

### <a id='pull-request'></a> Submitting a GitHub pull request

If you have identified a problem with the documentation and know the required content change, the fastest way to make the change is by submitting a PR.

The <%= vars.platform_name %> documentation team typically accepts PRs within a day, but might need to ask follow up questions.

Before your PRs can be accepted, you must have a signed Contributor License Agreement (CLA) on file. If you do not, you are prompted to sign a CLA once you have opened your first PR.

To submit a pull request:

1. Go to the topic that you want to modify.

1. To locate the GitHub source file that contains the content for the topic, scroll to the bottom of the page and click **Create a pull request or raise an issue on the source for this page in GitHub.**

1. Click the pencil icon to edit the file in GitHub.

1. Make your desired changes.

1. Under **Commit changes** at the bottom of the page, enter a description of your change and click **Propose file change**.

1. Click **Create pull request**.

1. Please put your PR in "Draft" state until you are ready for the Docs Working Group to review and merge it. This prevents us merging it before you are done with it / before all the review comments are in. When you are ready to have it merged, change the state to "Ready for Review."

### <a id='issue'></a> Raising a GitHub issue

If you do not have specific edits to make, but you want start a discussion or make a general suggestion, you can raise a GitHub issue.

GitHub issues take longer to resolve than pull requests. But if you describe the issue with helpful background information, and have specific and actionable instructions, the <%= vars.platform_name %> documentation team can quickly address it. Be sure to tag anyone who you think has more information or who will be interesting in helping with it.

Vague or partially-baked GitHub issues might remain unaddressed for some time.

To raise an issue on a GitHub repository:

1. Go to the topic that you want to modify.

1. To locate the GitHub source file that contains the content for the topic:
	1. Scroll to the bottom of the page.
	1. Click **Create a pull request or raise an issue on the source for this page in GitHub.**

1. Click the name of the repository where the topic is located. For example, `docs-dev-guide`.

1. Click the **Issues** tab.

1. Click **New issue**.

1. Enter a title for your issue, and in the text box, describe the issue and provide links to the relevant topics.

1. Click **Submit new issue**.

### <a id='non-github'></a> Contributing without GitHub

To contribute to the <%= vars.platform_name %> docs without using GitHub, you can use one of these methods:

* **Create a pull request or raise an issue on the source for this page in GitHub** (Cloud Foundry) on any page of the documentation.

* **Slack** the <%= vars.platform_name %> docs team through the [&#35;cf-docs](https://cloudfoundry.slack.com/messages/C03B0T0D5/") channel in <%= vars.platform_name %> Slack.


## <a id='advice'></a> Contributor advice

The <%= vars.platform_name %> documentation team reviews and revises all contributions, so you can **focus on providing correct and complete information, and not worry about style and structure**.

Keep in mind:

* If your contribution is larger than a small correction, put yourselves in the shoes of a novice and read through it. Revise the text to answer any questions that might occur to a less experienced user.

* Who needs this information? Are they a developer or a platform operator?

* What are the specifics that a user needs to know in order to understand and perform the task? Instead of "the instance" or "the cluster," explain the instance or cluster of what. Instead of "revise the code to...", explain where to revise the code.

* If you are giving instructions, include why you would want to do what you are describing. What is your specific situation, and what result do you seek?

For further guidance, contact the <%= vars.platform_name %> documentation team on our `#cf-docs` channel on the [<%= vars.platform_name %> Slack](https://cloudfoundry.slack.com).


## <a id='preview'></a> Previewing documentation changes

<p class="note">
<span class="note__title"><strong>Note</strong></span>
Since the docs pipeline has moved, this procedure is unlikely to work for you. If you need support, or it's very important to preview your changes before publishing, please ask for help on the Cloud Foundry Slack, #cf-docs. All submissions are reviewed for syntax and coherence before merging, but the Doc WG does not have CF experts to verify technical changes.
</p>

The <%= vars.platform_name %> documentation team uses the tool [Bookbinder](https://bosh.ci.cloudfoundry.org/teams/wg-docs/pipelines/cf-current) to publish the <%= vars.platform_name %> documentation.

The following instructions explain how to use Bookbinder to preview your documentation changes locally. But you do not have to install or use Bookbinder in order to contribute to the <%= vars.platform_name %> documentation.

To preview documentation changes with Bookbinder:

1. If you do not already have a workspace directory within your home directory, create one by running:

	```
	mkdir ~/workspace
	```

1. Identify the content repository where your documentation is located. For example, `https://github.com/cloudfoundry/docs-cloudfoundry-concepts`.

1. Clone the content repository. For example, to clone the `docs-cloudfoundry-concepts` repository, run:

 	```
 	git clone git@=github.com:cloudfoundry/docs-cloudfoundry-concepts.git
 	```

1. Return to your workspace directory and clone the <%= vars.platform_name %> book by running:

	```
	git clone git@=github.com:cloudfoundry/docs-book-cloudfoundry.git
	```

1. Change directory into the <%= vars.platform_name %> book by running:

	```
	cd docs-book-cloudfoundry
	```

1. To install the necessary gems, including Bookbinder, run:

	```
	bundle install
	```

1. To use Bookbinder to create a live version of your docs, run:

	```
	bundle exec bookbinder watch
	```

1. Start a browser and go to `http://localhost:4567` to where your docs are published. For instance, `http://localhost:4567/cf-cli/install-go-cli.html`.
	<br><br>
	Bookbinder automatically updates the live version of the documentation whenever you make a change to the content repository.