Convert docs to asciidoc

[felixbarny]

closes #99

[apmmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Build Cause: [Pull request #112 updated]

• Start Time: 2020-11-23T07:50:17.721+0000

• Duration: 8 min 15 sec

Test stats 🧪

Test	Results
Failed	0
Passed	127
Skipped	4
Total	131

[felixbarny]

Hey @bmorelli25 could you help with getting these docs to elastic.co?

[bmorelli25]

Awesome! Sure can 🎉

[bmorelli25]

OK, I pushed some changes that are required to build this PR locally. If export GIT_HOME="/<fullPathTYourRepos>", you can build these docs with the following command:

$GIT_HOME/docs/build_docs --doc $GIT_HOME/ecs-logging-java/docs/index.asciidoc --chunk 1 --open

I'll add comments to this PR for content recommendations.

[bmorelli25]

Here's my first round of suggestions on the content.

[bmorelli25]

I added a webhook for docs ci testing to this repo (hope that's ok!). It won't work correctly until elastic/docs#2010 is merged.

[bmorelli25]

@elasticmachine, run elasticsearch-ci/docs

[bmorelli25]

Sorry, last thing -- for now at least. What structure were you expecting? This is what we have right now:

I think it makes sense for all of the setup pages to be sub-pages of the getting started topic.

[felixbarny]

Thanks for the super quick and thorough review ❤️

I think it makes sense for all of the setup pages to be sub-pages of the getting started topic.

I agree. What's the best way to do that?

[bmorelli25]

No prob!

I agree. What's the best way to do that?

I'll add another commit that adjusts the heading levels to match the proposed layout

[bmorelli25]

I played around with this a bit more... what do you think of using tabs to display all installation options on one page? I'll screenshot an example below -- note that this isn't complete yet, just a prototype to give you an idea of what I'm talking about.

[felixbarny]

I like the aesthetics and how it makes the installation instructions more streamlined but it's a bit awkward that you can end up looking at the log4j2 instruction for adding a dependency and at the Logback instruction for the layout/encoder instructions. Or is it possible to synchronize the selection of a logger across all tabs?

[bmorelli25]

The selected tab is synched to all tab groups. You can play around with the functionality on this page to get a feel for it: https://www.elastic.co/guide/en/observability/7.10/ingest-logs.html

[felixbarny]

Ah, nice! Then let's go for it!

[bmorelli25]

Here's where we're at now. Let me know your thoughts.

[felixbarny]

Nice! I've extracted the structured logging section into it's own page as it's not necessarily a step to get started but some advanced capabilities of the log4j2 logger that are interesting after getting started.

[bmorelli25]

Great call. That section was getting a bit long.

[bmorelli25]

LGTM!