# Hacktoberfest 2022 (Oct)

###### tags: `Documentation`

## Hacking the Ansible docs

Ready to start editing Ansible documentation? Great!

You can edit docs directly in GitHub. You can also can clone or fork the Ansible repository and open a PR against the ``devel`` branch.

$ git clone [e-mail]:ansible/ansible.git

Visit [Contributing to the Ansible Documentation](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html) for more information on getting setup.

*NOTE* The following sections uses `grep` to find occurences. You can append ` | wc -l` to get a count of the numer of impacted files.

### Opening Issues
When opening issues, include a comment to say the following:
* For the month of October, we will address hacktoberfest PRs on a first come-first mergeable basis as there is no way for us to assign issues to an individual contributor. Thanks for your interest in helping the Ansible documentation effort!

Each issue should include the following:
* hacktoberfest and easyfix label
* limited scope to keep the PR under 50 files
* Not so limited scope that we get 100 PRs with single fixes each :-) Yes it's a balancing act.

We may still geet people asking to assign an issue to them. We don't have that ability, thus the comment above that PRs merged on first come first merged (for correct PRs).

Each followon PR should:
* thank the contributor, even if they did it incorrectly or are more spam than fix (like randomly changing a sentence that doesn't improve readability of the docs).
* Add hacktoberfest label to the PR
* Ensure the PR says "Fixes #xxxx" for the issue it is fixing so that issue is automatically closed when the PR merges.
*
### Remove urls that are raw (no context) or say 'here' - accessibility

* https://github.com/ansible/ansible/issues/78899
* https://github.com/ansible/ansible/issues/78914

### Update boolean use in guides (not modules) to use`true/false` in most places.

Based on https://github.com/ansible-community/community-topics/issues/116 we should use `true/false` in playbook and task examples (basically anything that `ansible-test` would use to validate the task).
**NOTE**: For now, avoid EXAMPLE blocks in any modules/plugins as some yes/no are valid (aka not boolean etc so require technical reviewers, and some folks still disagree on these changes).
(samccann evaluating and will open issues)
From `docs/docsite/rst`:

   $> grep -R '\: \(yes\|no\)$' --exclude-dir=locales --exclude-dir=network --exclude-dir=collections`

See the following issues to fix these:
* https://github.com/ansible/ansible/issues/78921
* https://github.com/ansible/ansible/issues/78922
* https://github.com/ansible/ansible/issues/78923
* https://github.com/ansible/ansible/issues/78924
* https://github.com/ansible/ansible/issues/78925

### Ensure IP addresses conform to RFC 5737

IP addresses used as examples in documentation should be within the ranges of 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2),
and 203.0.113.0/24 (TEST-NET-3) as per [RFC 5737](https://www.rfc-editor.org/rfc/rfc5737).

Procedures should use the loopback address `127.0.0.1` (localhost) to demonstrate running a process or service in a developer environment.

### Replace the instances using :: instead of code-block:

   $> grep -rn "^[[:blank:]]*[^[:blank:]\.\.].*::$"

### Use sentence case in headings

Sentence case is a capitalization style that mainly uses lowercase letters.

Follow these directions to change headings to sentence case:

* Capitalize the first word of the title or heading as well as all subheadings.
* Capitalize proper nouns as well as occurrences of Ansible or related software like Ansible Builder.
* Use lowercase for everything else.

For consistency, you should change all headings in the same guide.

### Replace Latin terms (via, e.g, i.e, etc)

From `docs/docsite/rst`:

   $> grep -R -e 'etc\.' -e 'i\.e ' -e 'e\.g\. ' -e 'via ' -e 'vs\(\.\)\? ' -e versus --exclude-dir=locales

**Note**: List has been pulled from https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/dev_guide/style_guide/index.rst#avoid-using-latin-phrases

* https://github.com/ansible/ansible/issues/78997
* https://github.com/ansible/ansible/issues/78998
* https://github.com/ansible/ansible/issues/78999
* https://github.com/ansible/ansible/issues/79000
* https://github.com/ansible/ansible/issues/79001
* https://github.com/ansible/ansible/issues/79002
* https://github.com/ansible/ansible/issues/79003
* https://github.com/ansible/ansible/issues/79006

#### Fix rstcheck v6 problems

spredzy: That sounds like a huge effort for hacktoberfest. Feel like we should decide which rule we want to gate on fix it, implement a new rules, etc... - A good suggestion might be more define **one** rule we want to be tackled during hacktoberfest
samccann: there is a small set of problems with rstcheck6 that we could potentially fix. I'll add examples when I have to time to regenerate the list. They may be in collections vs ansible/ansible...

#### Change usage of the word "please" for tone

Using the word "please" conveys friendliness and humanizes text.
However, in technical documentation, using "please" can reduce authoritative voice and lose meaning in translation.

Consider the following sentence: "Please open your browser."
This construction can be taken as a request rather than an imperative.
Using "please" does not clearly signal to users that they need to perform an action, which can cause users to fail.

1. Open a terminal in the RST source directory and search for the word "please".

    $ cd ansible/docs/docsite/rst
    $ grep -R 'please' --exclude-dir=locales

2. Consider revising constructions that use "please" to use a more authoritative voice.

#### Replace any problematic language and spelling errors

Search for problematic terms such as "master" as follows:

$ cd ansible/docs/docsite/rst
$ grep -R 'master' --exclude-dir=locales

**Note**: Haven't found any thing in that one. Most are either external repo having a branch `master`, or a variable named `master`.

Install codespell and search for problematic language and spelling errors:

$ cd ansible/docs/docsite/rst
$ codespell --skip "*.po" --ignore-words-list "ACI","aci"

#### search leadin sentences (examples, lists, etc)

Search leadding sentences to ensure they are complete:
* Don't do this - **Use the setup utility to**:
* Do this - **Use the setup utility to complete the following tasks:**

#### (?) Make tables more accessible to screen readers

TODO

#### Externalize code blocks to native file type

Embedding YAML, Python, INI code in RST files can be

#### Use "command" and "table" in the leadin sentences for commands / tables

TODO

# Opening Detailed Issues
See https://github.com/ansible/ansible/issues/75923 for a good example. The general guidelines are:
* limit the scope of the issue to one file if possible (this allows a contributor to use edit on github to fix the issue).
* Provide details of what is wrong, and exactly how to change it
* If this is a repeated issue, link to PRs that solve the problem in prior issues.
* Label issue with `hacktoberfest`.