Document ECS RFC process

[epixa]

I still need to reconcile the existing readme and contributing guide with these changes, but I wanted to put this content into a draft PR for visibility.

The rendered stages doc can be seen here: https://epixa.github.io/ecs/stages.html

[webmat]

@epixa Thanks for opening this.

What do you think is the best way to host this wide html table?

I think using Github sites as is will lead to unintended complexity. For instance, the main readme can be visualized, the links to other markdown files also work, but the experience is strange. Check out the generated/elasticsearch readme, for example: https://epixa.github.io/ecs/generated/elasticsearch/ :-)

[webmat]

Note that despite the added scope, I wouldn't mind getting a nice Github website going for ECS. Opens up interesting possibilities.

Also worth pointing out that to generate the stages.html file we could use asciidoc, Github renders it. Note that I'm not suggesting hosting this on the main Elastic docs site, as it's too narrow for the table. I'm just suggesting using Github's asciidoc rendering capabilities if we use Github website.

[epixa]

What do you think is the best way to host this wide html table? I think using Github sites as is will lead to unintended complexity.

I'm open to ideas because I don't love the github pages approach for a single document, but I don't think rendering in the github UI is an option here. The issue is that github enforces a max width on its rendered content that is too narrow for this table. I experimented with making the font size smaller to trade off accessibility for density, but the result was still not great. Manually adjusted column widths helps a bit, but that's not something you can do with generated content on github.

I settled on github pages because it requires no tooling and still uses github as the source of truth, so it seemed like a workable approach with the fewest moving parts.

[epixa]

I've pushed updates that include the RFC template. I ended up going with a single file with stage iterations described in comments. Most of the data is additive anyway, and I think this lends itself to the "living document" notion of the RFC until it is finished.

[ebeahan]

This is great - the documentation is comprehensive but accessible.

I noted only one open-ended question and a handful of nitpicks.

[webmat]

This is looking good. Got a few comments on 2 details.

After those I think we can merge and iterate as we start using this.

[andrewkroh]

LGTM. Just some redlines from me. Looking forward to seeing this in action.

I think Draft status can be removed given that we are reviewing it 😄 .

[epixa]

I pushed changes regarding all outstanding feedback

[webmat]

LGTM

We may have to iterate on making the "stages" table viewable in a sensible way. Did you intend to turn on Github pages for this?

[epixa]

@webmat Yep, my plan is to turn on github pages, so the stages doc will be accessible at https://elastic.github.io/ecs/stages.html (linked from PROCESS doc)

[webmat]

Do we need to turn it on for all of Elastic? And if so, should we ring other folks first? ;-)

[epixa]

No, it's a per-repo setting. Other projects in Elastic already use github pages, like EUI: https://elastic.github.io/eui/

[ebeahan]

LGTM