Provide Terse "Contributing Docs Fixes" Instructions

[jaredmorgs]

Through @mojavelinux 's patience, I've learned a few tricks about how contributions to the user guide should be handled.

• Naming your PR something like Issue-123 instead of issue_123 or bugfixes
• Always having a matching Issue number to go along with your PR, and reference the bug number in your PR.
• Using the git commit --amend as a low-friction way of squashing your commits as you create your PR.
• Keep changes atomic and in-scope of the fix.
• Certain standards about attributes.

Because the User Guide is probably the most landed-on guide out of the suite, it would be great to include a "Contributing Docs Fixes" section to the very top of the guide so folks can understand the suggested PR flow the project expects.

As a recent contributor, having the way to submit PRs clearly defined would help me be a more effective contributor. Both to Asciidoctor, and other open source projects.

We don't want to scare folks away from making a minor change. We just want to give them enough info to make their job easier.

[mojavelinux]

Absolutely! I love these suggestions.

Ever since I got into the habit of naming branches after issues, I've found it to really improve my workflow. I tend to use all lowercase and a hyphen, like issue-23. The really nice part about this is that when you go to write your commit message, you don't have to look up which issue number to mention in the message (e.g., resolves #23) because it's right there in the branch name.

Speaking of the message, I like to always have the first line of the message be resolves #xyz comment here where "xyz" is the issue number and "comment here" is a brief state of the problem being solved.

[jaredmorgs]

About milestones and docs (from @mojavelinux )

FYI, if an issue is scheduled against the support milestone, it means that I didn't see a need for a change to the docs. Of course, you can dispute that choice, I'm just letting you know how I'm using that milestone.

[mojavelinux]

I think we can also get some ideas from the documentation contributors guide from Infinispan.

See http://infinispan.org/docs/8.1.x/contributing/contributing.html#_writing_documentation_and_faqs

[jaredmorgs]

Also from issue #387 about writing sentence per line.

Putting a sentence per line makes it easier for someone to read code from the left margin and see each sentence. It also makes doing diff comparisons even easier than if sentences are run-on on the same line.

[jaredmorgs]

I think it's worth citing asciidoctor/asciidoctor#1407 here as well. There is already a healthy discussion about other contributing guides that should be considered.

I'm marking this as something that should be considered for a hackfest. Thoughts about that @mojavelinux ?

[mojavelinux]

This printable git cheatsheet could be a useful reference to help navigate the git waters.

http://zeroturnaround.com/rebellabs/git-commands-and-best-practices-cheat-sheet/

[mojavelinux]

When I think about how I work, there are just a few techniques I use over and over without ever running into problems. I am far, far, far from a git master. It's just that I know exactly what everyday commands to issue so that I avoid getting hung up. The key is to figure out how to describe those techniques so that anyone coming along can follow them.

• how to create a branches to work on
• how to switch between branches
• when to amend a commit
• when to rebase
• how to force push a branch
• how to fast-forward merge to master (to catch up)
• how to send a pull request to another pull request

[mojavelinux]

@rockyallen identified several writing conventions that you can now find at the top of the user manual. https://github.com/asciidoctor/asciidoctor.org/blame/master/docs/user-manual.adoc#L3-L11 We should consider formalizing these in this section as well. We don't want to go overboard with the conventions, but a few will help instill confidence in contributing authors.

While discussion at a hackfest could certainly help move this issue forward, I think it primarily needs to be managed asynchronously via this issue. For issues like this, the best way to get things started is to post drafts in a comment, sort of using the comment stream as a whiteboard.