search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
323 stars 803 forks source link

Provide Terse "Contributing Docs Fixes" Instructions #468

Open jaredmorgs opened 8 years ago

jaredmorgs commented 8 years ago

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

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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.

mojavelinux commented 8 years ago

@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.