Update SE and MP guides to adopt new review feedback

[tjquinno]

Romain and Joe supplied some good feedback about the first guide. This task incorporates that feedback into the first guide.

This is important to do now so future guides can use the SE RESTful web app one as a pattern.

Here is my list of the topics we covered:

1. Change guides to use the Helidon archetype.
2. Because comment out docs and sitegen plugin for now #1 generates a lot of Java code, change the guide from largely adding code to largely explaining the code that is generated. Some code (e.g., metrics and health) will still be added.
3. Link to or include pre-req information from the separate, common file.
   a. Maybe a simple approach is for the common AsciiDoc attribute assignment file to assign attributes containing pre-req versions so the guide .adoc files can refer to those.
   b. Another approach would be for the existing pre-reqs info in the Getting Started file to be tagged so individual guides can include only the pre-reqs they need.
4. Add default attribute settings in the guide so GitHub rendering works correctly. (Will evolve over time as the common AsciiDoc attribute assignment file appears.)
5. Change ReSTful to RESTful. (done as part of Updates and additions for the MP RESTful web service guide #215)
6. Migrate the guide files from src/main/docs/index.adoc to top-level README.adoc. Part of this item is to make sure the README.md renders properly, esp. regarding includes.
7. Break long command lines explicitly to avoid horizontal scrolling of code blocks on small screens. (done in Updates and additions for the MP RESTful web service guide #215)
8. See about inlining the startServer() code block.
9. Change output code blocks top reformatted (so suppress the built-in copy feature on our site). (done in Updates and additions for the MP RESTful web service guide #215)
10. Specify the exact git clone command in the last section for cloning the repo.
11. Fix list problem after the HTTP method table. (done in guide se-restful-webservice incorrect list #168)
12. See Joe’s example from Getting Started to narrow tables where possible.
13. See if there is a way to strip indentation from included code snippets.

[tjquinno]

@romain-grecourt @barchetta FYI some bad news...It turns out that GitHub does not support the AsciiDoc include directive. I used it heavily in the guides.

github/markup#1095

The issue makes a reference to perhaps being available "next year" (2019).

[romain-grecourt]

@tjquinno That's fine with me :D - I actually would prefer linking the pre-req ; it does not make the guide self contained but makes it lighter.

It goes against the rule of "links are bad", but we could be smart and have a little section at the top like "before you begin" where we list the things that must be done before following a guide.

[tjquinno]

I'm not so concerned with the pre-requisites. The current guides pull in a great deal of code from the source .java files, pom.xml, resource files, etc. and use callouts to discuss why bits of code are there. In a branch I moved the AsciiDoc to README.adoc at the top level and it's full of ugliness like this:

(see the link:xxx parts)

We can still move the .adoc files to README.adoc at that top level but GitHub will not render it nicely -- not unless we change how the included content in the guides will be handled on GitHub and I don't know what we can do to improve the situation, other than waiting for GitHub to fix this.

[romain-grecourt]

Yikes, I missed that. One other way would be to not use the include directives at all but instead duplicate the content.

The duplication sucks, it means we'd loose the advantages of using the include directives.
We could workaround that with custom maven plugin and match the snippets in the adoc files with their corresponding sources. I.e add a couple of annotation in the adoc files so that we know what files and what snippet to match with, then we can add some check in the pipeline to verify these.

This sounds like a potential good idea, we could also be smart and fix the indentation issues we get with the include directives.

[tjquinno]

Yes, I was wondering what our options might be to do something like that.

About the indentation with includes... I think there are further options on the include directive I have not tried. Anything clever we do with a custom maven plug-in should honor normal AsciiDoc as much as possible so, if and when AsciiDoc-on-GitHub improves we can take advantage without having to rework our .adoc source.