security.adoc: document how to get Github Auth and Swarm plugins to play together

[jimklimov]

Following a setup of a new Jenkins instance where we wanted both Github authentication and dynamic Swarm agents, and hit some roadblocks along the way, I summarized the findings which impact the setup of both these plugins in order to both have a cake and eat it.

• Make sure you are opening from a topic/feature/bugfix branch (right side) and not your master branch!
• Ensure that the pull request title represents the desired changelog entry
• Please describe what you did
• Link to relevant issues in GitHub or Jira
• Link to relevant pull requests, esp. upstream and downstream changes
• Ensure you have provided tests - that demonstrates feature works or fixes the issue

[basil]

Thanks for documenting this! While the structure and content needs some editing, the information is much appreciated. I am sure users will benefit from your experience here.

For someone who was talking about being lost in a wall of text in another PR, you sure do know how to write a wall of text. ;-) The tone of these 8 paragraphs reads more like a blog post than a user manual. Rather than describing your own personal experience, can
you phrase this in the form of instructions for an end user who is trying to accomplish some specific objective? For example, rather than "I verified X", try "A common practice is to X". Rather than "I verified X on Y works", try, "Configure X on Y". Rather than "I verified that Z didn't work", try "Z is not supported because…", etc.

More generally, 8 consecutive paragraphs of anything in technical documentation indicates that the writing lacks structure. If you have that much content, try breaking it up into a few subheadings, each of which has at most 3-5 paragraphs. The user should be able to click through from the table of contents to an area where they can find what they are looking for by just reading a few paragraphs.

From a grammatical perspective: "Github" should be capitalized "GitHub", "Autorization" is spelled "Authorization", non-English words like github-oauth-plugin should be surrounded by backticks, and "swarm" should be capitalized "Swarm."

Also the recommended practice in AsciiDoc is one sentence per line. Any sentence that begins with "Note that" is probably a candidate for a "NOTE:" AsciiDoc admonition. Also the JIRA link isn't valid AsciIDoc doesn't display correctly.

[jimklimov]

Thanks for the review, I'll try to rearrange that.

Is it also permitted to line-break the paragraphs before ~80-char length? I mean I know Asciidoc supports that, and find it very convenient for editing in a terminal, but not sure about particular project's source style guidelines so stuck with following the precedent.

Typos notwithstanding, I was a bit lost about GitHub spelling since that plugin often uses lower-case "h"...

As for "recommended practice", it was in my draft but I wondered if I can throw such claims around based on a single experiment (and so not poked from various possible aspects), done an hour before posting? So I sort of just third-personalized my post in JIRA in the end :)

[basil]

Is it also permitted to line-break the paragraphs before ~80-char length?

It's permitted but not recommended for the reasons explained here.

[jimklimov]

How does it look now? :)

NOTE: The phrasing of "Github Authentication Plugin" (with lower-case "h") is from their option in $JENKINS_URL/configureSecurity/

[basil]

I left a few minor suggestions. I'll probably go back and edit this some more after it's merged, but this is good enough for now. Thanks for all this information.