Mat's review of static asciidoc files #393
Conversation
|
@ruflin @karenzone @MikePaquette @MarkSettleES I'd like a preliminary look at this pass on the asciidoc for static pages. This is my take on all everything other than the actual ECS field definition files, which was covered by #347. I'd like your feedback on if you think this is a good direction, if you see any issues with this. I've moved things around and added a few paragraphs, but I haven't taken out anything. |
MikePaquette
left a comment
MikePaquette
left a comment
There was a problem hiding this comment.
Left of set of review comments throughout. At higher level, there seems to be overlap between "converting", "Contribution Guidelines" (not part of this PR), and "using-guidelines."
docs/converting.asciidoc
Outdated
| + | ||
| Populate core fields first. Look at your set of event fields, and find | ||
| the appropriate ECS field name for each one. | ||
| the appropriate ECS field name for each one. |
There was a problem hiding this comment.
This section needs to be clarified/simplified here and wherever else it is used. Suggestion:
- Review each field in your original event and map it to the relevant ECS field.
- Start by mapping your field to the relevant ECS Core field.
- If a relevant ECS Core field does not exist, map your field to the relevant ECS Extended field.
- If no relevant ECS Extended field exists, consider keeping your field with its original details, or possibly renaming it using ECS naming guidelines and attempt to map one or more of your original event fields to it.
- Review each ECS Core field, and attempt to populate it with data from the relevant field or fields from your original event.
There was a problem hiding this comment.
Really love this. I'm pushing this to the PR right away. I've used this and added a few small but important things.
I really love how much clearer the steps are becoming :-)
| === General guidelines | ||
| ==== Types of fields | ||
|
|
||
| ECS defines "Core" and "Extended" fields. |
There was a problem hiding this comment.
Again, should mention that these are "levels" indicated in the levels column, and these should be consistent with those listed in the converting asciidoc file.
|
I think the PR is ready for another round of review. I've addressed a lot of @MikePaquette's feedback. His feedback also inspired me to rewrite and clarify more parts of the documentation. I've removed links and sections that I don't think will be ready on Tuesday. We can add those back as soon as they become available. I still see 3 todos to address for this to be ready to go, as listed in the body of this PR. Ideas welcome there :-) |
|
@webmat The doc still builds without blowing up, so that's half the battle! |
…on is about. The sidebar selector is probably not there in the PDF books :-)
Featuring what ECS actually **is**, as opposed to what it does :-)
Other page simply links to it, to reduce duplication of content. The 'converting' page is just a series of pointers, and shouldn't be the canonical source of any fundamental information that defines the schema.
|
Ok, I've updated this PR in such a manner that I consider it ready for final review. I've addressed two of the todos in the body. Converge on canonical ECS definition I've updated it with my latest proposal, which I've also made in elastic/stack-docs#254. I think it's high enough level to fit in a glossary. Being for the ECS glossary, I still kept quite a bit of details (which may get trimmed out for the main site glossary). I've also taken Mike's proposal in this comment #393 (comment) and made it the content of the "What is ECS?" section of the Overview. I think it's a great detailed definition. Reconcile using-guidelines.asciidoc and converting.asciidoc Both places used to mention the ECS levels. We had improved the wording in the "converting" page, which is meant to be informal pointers. I've therefore moved the improved definitions to the "guidelines" page, which is the official guideline on how we implement ECS. More glossary definitions I'm too into ECS to know if anything more is needed there. Let's add them as the need arises, and not block this PR for this. Other notable changes
|
webmat
changed the title
3 participants
In this PR I'm going over the static asciidoc files, and getting things ready for the move to the main website.
Both the content of the files is being modified, and the overall structure of the documentation.
I'm trying to sequence sections in chronological order of learning/discovery of ECS. Please let me know what you think of this proposed structure. I'm also trying to address end users as much as implementors.
New Nav Structure
TODO