Line edits for contributing.rst #135
Conversation
This is an effort to keep all titles in the imperative tense.
contributing.rst
Outdated
| @@ -221,7 +221,7 @@ You can install the SDK Platform tools (including :command:`adb`) as a `standalo | |||
|
|
|||
| .. _docs-workflow-setup: | |||
|
|
|||
| Getting Ready to Work | |||
| Get Ready to Work | |||
There was a problem hiding this comment.
This is an editorial change, not a typo fix.
Please revert.
(We should have a discussion about gerunds in titles separately.)
| @@ -619,9 +619,9 @@ In order to facilitate efficient :ref:`cross-referencing`, sections should be la | |||
|
|
|||
| Lorem ipsum content of section blah blah. | |||
|
|
|||
| The section label should usually be a sluggified version of the section title. | |||
| The section label is a sluggified version of the section title. | |||
There was a problem hiding this comment.
But it isn't always.
There was a problem hiding this comment.
If there isn't a reason it shouldn't be then shouldn't we push the narrative that it is? Otherwise it might just creates confusion in the mind of the reader - or at least that was my thinking.
There was a problem hiding this comment.
I see your point. But here's my thinking:
- I don't want someone coming through and "helping" by doing line edits to correct existing section labels.
- Sometimes you want a short, clear label but it makes sense to have a longer, descriptive, human-readable title.
- Sometimes you change the human readable title. But the label should typically not be changed, as it might have cross references.
You might be right about this, though.
But a line edit isn't the place to have this discussion.
Add a note to the Style Guide issue, that this is something we should hash out. In the mean time, leave this instruction in place.
There was a problem hiding this comment.
Thank you for your detailed reply. I will do as you suggested and add these points as a comment to the Style Guide issue.
contributing.rst
Outdated
| - no spaces | ||
| - hyphen separators | ||
| - be short yet descriptive | ||
| - contain only lower case charecters |
| @@ -632,7 +632,7 @@ Section titles must be unique throughout the entire documentation set. Therefore | |||
|
|
|||
| .. _aggregate-getting-started: | |||
|
|
|||
| Getting Started | |||
| Get Started | |||
There was a problem hiding this comment.
Editorial, not typographical.
contributing.rst
Outdated
|
|
||
| Section titles must be unique throughout the entire documentation set. Therefore, if you write a common title that might appear in more than one document (*Learn More* or *Getting Started*, for example), you'll need to include additional words to make the label unique. The best way to do this is to add a meaningful work from the document title. | ||
| Section titles must be unique throughout the entire documentation set. Therefore, if you write a common title that might appear in more than one document (*Learn More* or *Get Started*, for example), you'll need to include additional words to make the label unique. The best way to do this is to add a meaningful work from the document title. |
Remove working with docs using Cygwin section
This is with reference to Issue No. #96
These are a bunch of quick fixes to minor issues I found while reading contributions.rst. I figured that this was as good a place to start as any.
Proposals: I would like to add a line talking about the variant of English used throughout the docs. I would also like to add some missing points in the "submit a PR" section wrt getting changes from upstream.