search

elastic / uptime

This project includes resources and general issue tracking for the Elastic Uptime solution
12 stars 3 forks source link

Creation of uptime product book #7

Closed justinkambic closed 5 years ago

justinkambic commented 5 years ago

We'll need to create a new documentation section for Uptime, similar to Logging and other solution-level products.

The docs for the other Observability solutions for 6.6 are relatively brief, they cover the features and the expected use cases. Docs for Uptime will probably be roughly the same size, I'd expect we would maintain two pages, one documenting the Overview and an explanation of the data available on that page, and likewise for Monitor.

It may be worth having a short discussion about this before interfacing with Docs; I'm fine with using this issue for it. If a more formal proposal is needed I am fine with taking the initiative in drafting that.

justinkambic commented 5 years ago

cc @dov0211 @andrewvc

justinkambic commented 5 years ago

To further update this issue, @andrewvc has been working with @bmorelli25 to map out what's required of us, and has taken the initiative on creating our initial Uptime documentation.

dov0211 commented 5 years ago

Those are the necessary places I had mapped out

bmorelli25 commented 5 years ago

Posted this in #20 as well - We're good to move forward with creating a documentation book for uptime 🎉.

justinkambic commented 5 years ago

@bmorelli25 I think @dov0211 has offered to take the lead on this but I am also willing to help if needed.

dov0211 commented 5 years ago

@bmorelli25 , let us know what is needed and how do you think the demo book should be structured I had started this google doc where we should all collaborate on

bmorelli25 commented 5 years ago

Sorry all, was on vacation. Will take a look at the doc tomorrow. Might be good to schedule a call at some point to chat as well. Would love to include Marjorie (the new Observability tech writer) as well!

bmorelli25 commented 5 years ago

See next comment for plan of action.

~Alrighty, so I'm seeing two initial phases here:~

~Phase 1~ ~* Adding the information in this google doc to the Uptime "Overview" section in Kibana.~

~Phase 2~ ~* Moving all uptime documentation out of Kibana into its own book. We're not quite ready to do this yet, but the same thing will happen with APM and Infra documentation. With this, there will still be a header in the Kibana book with a sentence or two on what Uptime is, and a link to the new doc book.~

bmorelli25 commented 5 years ago

Recap of conversation with the uptime squad. Please edit if I missed anything. Also, adding in @Titch990.

Phase 1 - 7.3

Phase 2 - 7.4?

Remaining questions:

dov0211 commented 5 years ago

@bmorelli25 Since we reached FF, I think that now is the right time to finalize phase 1 of the suggested plan

bmorelli25 commented 5 years ago

Hey team. I'd like some guidance on the outstanding question: What repo should Uptime documentation live in? There are quite a few options: stack-docs, uptime, kibana, beats, observability, etc. Keep in mind that this is not where the docs will be built to, just where the source will live. I see two main options:

Kibana repo - Keep the documentation source in Kibana. This doesn't mean the docs would be built into the Kibana repo forever. We'd create a different uptime documentation folder and build that folder to the new "Uptime guide". The benefit here is that code and docs updates can be made in the same PRs.

Uptime repo - Since not all of your work is done in the Kibana repo, perhaps it makes more sense to pick a middle ground repository for all of the documentation to live in. We lose the ability to push docs with code, but maybe that's ok?

andrewvc commented 5 years ago

@bmorelli25 is there any prior art here?

I'm a bit reticent about this repo because then we need to and track releases here. That makes me lean toward Kibana, though it is imperfect from a taxonomical perspective.

bmorelli25 commented 5 years ago

I'm a bit reticent about this repo because then we need to and track releases here.

This is a really good point. Perhaps two better options are the Kibana repo, or the stack-docs repo.

elastic/stack-docs is home to siem, the infrastructure monitoring guide, install/upgrade guide, machine learning, and many other "accross the stack" documentation books.

APM chose not to use stack-docs, but to instead keep our overview documentation in APM related repositories. The APM Overview docs live at elastic/apm-server/docs/guide, side by side with the APM Server documentation. I kind of see this as prior art for the idea of keeping your docs within the Kibana repo.

andrewvc commented 5 years ago

Do you have a preference between repos @bmorelli25 ? It's a toss-up for me. I'm fine keeping docs in Kibana if that's the simplest path.

justinkambic commented 5 years ago

IMO - I'm fine with using Kibana for the present time.

I can envision a future where we'd move them to observability as conventions for these things mature, but I don't think it's an initiative we want to try to lead at this time.

bmorelli25 commented 5 years ago

Thanks for the input! Let's move forward with the Kibana repo. I'll get started on this project tomorrow.

andrewvc commented 5 years ago

Closing with merge of https://github.com/elastic/docs/pull/972