Discuss: place to store README.md templates

[mtojek]

Currently, README.md template files are stored in dev/import-beats-resources/<integration>docs/README.md. The place is aside from the integration, which might be confusing for contributors.
The original assumption was to generate integrations from Beats files. If there is a cut off date in the future to stop generating and modify already generated integrations, the current routine might be a problem.

README.md files are rendered from template during import step:

• exported fields are converted to a table

Questions:

1. Should README files be rendered during the package build step? What are the requirements to perform this?
2. Should we move README template files to Beats instead of import-beats-resources?

[ruflin]

When the processing happens does not matter too much in the case of the imported packages as these are not manually modified. But lets take the case where we are building a package that is not imported.

I'm building a new package with a README. I want to have a fields.yml documented in there and nice data.json. My initial approach would be to manually modify the README file every time I update fields but this will get out of sync quickly. So also in this case I would like to use the nice templating to generate the fields.yml and the data.json inside my readme. Because of this, I think needs to happen during the build stage.

For question 2: The main problem I see not having it in Beats is that someone will update the README on the Beats side but will not know about this file ...

[mtojek]

For reference: elastic/package-registry#313 (comment)

[exekias]

I'm wondering, does it make sense that we always add the fields to the readme, either manually or automatically, when these fields are defined and accessible by Kibana?

How about solving this from the UI? that would allow for more flexibility when browsing them (ie allow to collapse/expand them) and richer experience in the future (ie, showing units, link to metrics explorer to graph them, etc)

[ruflin]

I could see that we support this in the future but for now I would like to push this out to the creators of the packages. One of the reasons is that for example also our website will consume these assets and would then also have to implement the templating code. We had in the beginning the discussion around templates in the README but realised to keep things simple it should be just an file we don't process for now.

[mtojek]

I think we found the place. It would be great to keep them inside of the integrations, in the _dev directory.

It will be part of elastic/elastic-package#151. Resolving this one.