Documentation for contributing Elastic Packages

[ycombinator]

We are getting to a place where we want external contributors (partners, community, etc.) to author and publish packages to the Elastic Package Registry. To make this experience as smooth as possible for them, we need to have well-written and well-organized documentation.

Currently, we have two major sources of documentation around contributing packages:

• The integrations repository: https://github.com/elastic/integrations/blob/master/CONTRIBUTING.md
• The elastic-package repository: https://github.com/elastic/elastic-package/blob/master/README.md

We have been using these two sources for Elastic-internal contributors so far.

However, for external contributors, it might be better to have a single book, probably housed in this repository so it can be published to elastic.co like all our other product documentation. As we develop this single, cohesive book we could potentially phase out the documentation in the integrations and elastic-package repository and link from there to relevant sections of the book.

[ycombinator]

cc: @exekias (per our discussion yesterday), @mtojek, @sorantis (to consider for the developer experience theme for the next few iterations), @ruflin, @masci, @andresrc.

[sorantis]

Documentation is key to accelerating package development and contributions. This issue will replace my note in the project. I suggest we aim at a first stab for these docs in 7.14.

[exekias]

One point that is not covered by the description but still important is: How to develop a new input?

I'm ok if we target first the integrations that will just reuse existing inputs, but want make sure we keep this one in the radar.

[ycombinator]

I suggest we aim at a first stab for these docs in 7.14.

I'd love to get with a tech writer and get this project started. Who is the most appropriate tech writer I could reach out to about this?

[ycombinator]

@sorantis @exekias @masci @andresrc @ruflin is there a tech writer in particular we should reach out to for this work?

[andresrc]

we are trying to finish all the non-fleet-retated stuff for 7.13 this week, let me look at it with the team and try to assing someone next week.

[ycombinator]

let me look at it with the team and try to assing someone next week.

hi @andresrc, any updates on this?

[andresrc]

@bmorelli25 will be driving this effort from the docs team, thanks!

[ycombinator]

Thanks @andresrc.

@bmorelli25 I'll ping you on Slack so we can figure out the first steps here.

[ycombinator]

@bmorelli25 and I had an initial kickoff meeting over Zoom. Summarizing:

• we'll host these contributor docs on elastic.co, similar to https://www.elastic.co/guide/en/beats/devguide/current/beats-contributing.html (but likely a lot more extensive).
• we'll keep the sources for these docs in this repository, along side other docs that are being published to elastic.co, under https://github.com/elastic/observability-docs/tree/master/docs/en.

Next steps:

• @bmorelli25 is going to take some time to poke around the existing internal documentation, starting at https://github.com/elastic/integrations/blob/master/CONTRIBUTING.md but also following the links to related documentation in associated repositories to get a better sense of the content and scope.
• @bmorelli25 and I will meet again, no sooner than a week from today to go over his findings and discuss his ideas. At that point we should be able to come up with a checklist of slightly more concrete next steps, which we'll post here on this issue.

[ycombinator]

Met with @bmorelli25 again yesterday. He has been exploring the existing, internal-facing documentation and has come up with a rough developer guide with placeholders for areas that are not clear to him.

One thing he brought up in our meeting was that there is currently no good documentation that maps what an end-user sees for an integration (dashboards, configuration UI in Fleet, etc.) to the files/folders within an integration package. We brainstormed about this and tried to come up with a journey that uses Apache as an example. This journey is written from the perspective of someone who understands how best to observe Apache and now wants to create an integration package, step-by-step, to make this observability happen. @bmorelli25 is now working on fleshing out this journey.

[bmorelli25]

👋 Hey everyone. Like @ycombinator mentioned, I'm still working on fleshing out the integration developer journey. I have a WIP PR and preview up:

• Preview: https://integration-dev-guide.docs-preview.app.elstc.co/guide/en/integrations-developer/current/index.html
• PR: Integrations developer guide #769

This is still in the early stages, so the structure, content, etc., are all subject to change. Any feedback, concerns, or suggestions are appreciated.

[sorantis]

thanks @bmorelli25 for the draft. left some comments on the PR.