Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Line edits for contributing.rst #135

Merged
merged 8 commits into from
Sep 11, 2017
Merged

Line edits for contributing.rst #135

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ffc6f9f
fix typo environement -> environment
tanvibhakta Sep 11, 2017
b9cf318
change tense from future to present imperative
tanvibhakta Sep 11, 2017
4a3a5dd
change all 'getting' phrases to 'get' phrases
tanvibhakta Sep 11, 2017
ffc0dba
improve grammer of the image-file-names guideline
tanvibhakta Sep 11, 2017
5d7ca66
fix grammer with image-name-guidelines
tanvibhakta Sep 11, 2017
97d4708
fix grammatical error, change active to passive voice.
tanvibhakta Sep 11, 2017
7a72c1d
add warning tag to warning
tanvibhakta Sep 11, 2017
7d87e67
fix typo, revert editorial fixes.
tanvibhakta Sep 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ Check to see if you have virtualenv installed:

$ virtualenv

If you get a help message with information about commands, you have it. If you don't have it, you'll get a ``command not found`` message.
If you get a help message with information about commands, you have it. If you don't have it, you'll get a ``command not found`` message.

If you don't have it, the easiest way to get it is to use pip:

Expand All @@ -125,7 +125,7 @@ Now, inside that odk directory, create a python3 virtualenv.

The last part, ``odkenv`` can be whatever name you'd like to call it.

Activate your virtural environement with:
Activate your virtural environment with:

.. code-block:: rest

Expand Down Expand Up @@ -167,10 +167,10 @@ If you are adding binary files to the repo, and they are in formats not already

.. code-block:: none

# file type section heading
# file type section heading
*.{extension-to-track} filter=lfs diff=lfs merge=lfs -text

You can also use the command line.
You can also use the command line.

.. code-block:: none

Expand All @@ -180,11 +180,11 @@ This will add a line to :file:`.gitattributes`.

We would also appreciate it if you would keep that file organized by placing the new file format declaration in the appropriate section, or creating a new section as needed.

.. warning::
.. warning::

Updates to :file:`.gitattributes` must be done in a commit before the commit that adds the new binary files.
Updates to :file:`.gitattributes` must be done in a commit before the commit that adds the new binary files.

**We will not accept Pull Requests that include binary files untracked by GLFS.**
**We will not accept Pull Requests that include binary files untracked by GLFS.**


.. _android-tools:
Expand Down Expand Up @@ -619,7 +619,7 @@ 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But it isn't always.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your detailed reply. I will do as you suggested and add these points as a comment to the Style Guide issue.


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.

Expand All @@ -632,7 +632,7 @@ Section titles must be unique throughout the entire documentation set. Therefore

.. _aggregate-getting-started:

Getting Started
Get Started
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Editorial, not typographical.

-----------------

.. _basic-markup:
Expand Down Expand Up @@ -1166,12 +1166,12 @@ Image File Names
""""""""""""""""""


Image file names should be:
Image file names should:

- as short as possible while still being descriptive
- all lower case
- no spaces
- hyphen separators
- be short yet descriptive
- contain only lower case characters
- have no spaces
- use hyphens as the separator

Good image file names:

Expand Down Expand Up @@ -1211,12 +1211,13 @@ Now, at the command line, from the root directory of the :file:`odk-docs` repo:

python ss.py {document-name}/{image-name}

- ``{document-name}`` is the filename (without extension) where the you will use the image
- ``{image-name}`` is the name (without extension) you are giving the image

- be sure you are not overwriting an existing image
- ``{document-name}`` is the filename (without extension) where the image will be used.
- ``{image-name}`` is the name (without extension) given to the image.
- follow the :ref:`image-names` guidelines

.. warning::
Be sure you to not overwrite an existing image.

.. tip::
If you have a problem running ss.py, check to make sure your :ref:`Python 3 virtual environment <docs-venv>` is activated.

Expand Down