[Uptime] 7.8 docs by justinkambic · Pull Request #66118 · elastic/kibana

justinkambic · 2020-05-11T20:36:19Z

Summary

Adds docs to 7.8. We'll forward-port this change to master after merging.

Checklist

Delete any items that are not applicable to this PR.

Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support
Documentation was added for features that require explanation or tutorials
Unit or functional tests were updated or added to match the most common scenarios
This was checked for keyboard-only and screenreader accessibility
This renders correctly on smaller devices using a responsive layout. (You can test this in your browser
This was checked for cross-browser compatibility, including a check against IE11

For maintainers

This was checked for breaking API changes and was labeled appropriately

elasticmachine · 2020-05-11T20:36:22Z

Pinging @elastic/uptime (Team:uptime)

andrewvc

Thanks so much for adding these. Looks like there's an extra image file named Screen Shot 2020-05-11 at 2.44.25 PM.png . Left some additional comments as well. Would be great to get @bmorelli25 's feedback as well.

andrewvc · 2020-05-11T23:07:16Z

docs/uptime/certificates.asciidoc

Our docs generally use the active voice ( I can't find a citation, but maybe @bmorelli25 has one?) . This could be written: "Use the certificates page to visualize all of your TLS certificates..."

The Elastic guide to writing style talks about active voice.

Please have a look at 24ff319 where I've tried to prefer active voice as much as I could. I also tried to simplify a large chunk of the copy I had added.

andrewvc · 2020-05-11T23:09:53Z

docs/uptime/settings.asciidoc

Active voice: "Specify thresholds for all TLS certificates on the settings page"

andrewvc · 2020-05-11T23:10:31Z

docs/uptime/settings.asciidoc

I don't think we need to be this descriptive, that part of the app is self explanatory. IMHO we shouldn't document the obvious. Would like @bmorelli25 's thoughts here.

Perhaps the content would be better if it described what the fields vs. documenting their existence. Rephrasing this as: "Use the certificate maximum age field to control the number of days before expiration Uptime should display the certificate as being in a warning state. Warnings for maximum certificate age can also be set here. Some user agents and browsers consider certificates invalid after a certain amount of time.

Agreed. But looking at the screenshot, I only see "Expiration threshold" and "Age limit" as options. The docs should match those names. I'd alter Andrew's recommendation to something like this:

The settings page also allows you to specify thresholds for displaying and alerting on TLS certificates. Use the expiration threshold to specify <>, and the age limit field to control the <>. Some user agents and browsers consider certificates invalid after a certain amount of time.

andrewvc · 2020-05-11T23:16:34Z

docs/uptime/settings.asciidoc

This could be moved up IMHO to make the importance more clear.

Yes, this should be in the first paragraph

…ersion of this after we merge updated defaults for age limit threshold.

justinkambic · 2020-05-12T17:57:25Z

Looks like there's an extra image file named Screen Shot 2020-05-11 at 2.44.25 PM.png

This was supposed to be a draft but I guess I marked it as ready 😿

I left that as a placeholder to remind me to re-take that screenshot after #66135 was merged. I have subsequently added commits that fix this.

bmorelli25 · 2020-05-12T18:10:53Z

docs/uptime/settings.asciidoc

+For example, you may want to make sure that none of your organization's TLS certificates have been
+valid for longer than one year. This is becoming a common security requirement. Modifying the `Age limit`


Suggested change

For example, you may want to make sure that none of your organization's TLS certificates have been

valid for longer than one year. This is becoming a common security requirement. Modifying the `Age limit`

For example, a common security requirement is to make sure that none of your organization's TLS certificates have been valid for longer than one year. Modifying the `Age limit`

Updated in 4a63705.

justinkambic · 2020-05-12T18:29:16Z

What about something simpler

@bmorelli25 I updated the copy in 141c28e. Thanks!

Feel free to comment on any more of the copy I've added, these recommendations are super helpful.

bmorelli25 · 2020-05-12T18:57:52Z

docs/uptime/alerting.asciidoc

@@ -0,0 +1,26 @@
+[role="xpack"]


When I view the documentation preview for this page, I'm presented with two images without any context: http://kibana_66118.docs-preview.app.elstc.co/guide/en/kibana/7.8/uptime-alerting.html

I think we should move the paragraphs (context) above each of the screenshots.

Changed this in f0a0de9.

bmorelli25 · 2020-05-12T18:58:54Z

docs/uptime/alerting.asciidoc

+== Uptime alerting
+


Should we add an alerting overview here? Something like:

The Uptime app integrates with Kibana's {kibana-ref}/alerting-getting-started.html[alerting and actions] feature. It provides a set of built-in actions and Uptime specific threshold alerts for you to use
and enables central management of all alerts from <<management,Kibana Management>>.

Updated in 0495751.

justinkambic · 2020-05-15T21:04:10Z

@elasticmachine merge upstream

EamonnTP · 2020-05-21T16:49:40Z

Hi @justinkambic Would it be possible to merge this PR before Wednesday? Next week, as part of the Observability docs restructuring, I plan to move the Uptime documentation in the Kibana reference to the Uptime guide and it would be great to include this new content. Thanks!

justinkambic · 2020-05-26T13:20:45Z

@elasticmachine merge upstream

* Refresh existing docs images. * Add tls-related images. * Add certificates page to docs. * Update settings page with explanation of cert threshold fields. * Add placeholder image of updated settings page. Will need finalized version of this after we merge updated defaults for age limit threshold. * Add new alerting docs page. * Refresh settings page image. * Implement feedback and re-write/simplify some sections. * Clean up words. * Implement feedback on sentence structure. * Improve copy on alerting page. * Improve copy on settings page. * Update layout on alerting page. Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

* Refresh existing docs images. * Add tls-related images. * Add certificates page to docs. * Update settings page with explanation of cert threshold fields. * Add placeholder image of updated settings page. Will need finalized version of this after we merge updated defaults for age limit threshold. * Add new alerting docs page. * Refresh settings page image. * Implement feedback and re-write/simplify some sections. * Clean up words. * Implement feedback on sentence structure. * Improve copy on alerting page. * Improve copy on settings page. * Update layout on alerting page. Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

justinkambic added v8.0.0 Team:Uptime - DEPRECATED Synthetics & RUM sub-team of Application Observability release_note:skip Skip the PR/issue when compiling release notes v7.8.0 v7.9.0 labels May 11, 2020

justinkambic self-assigned this May 11, 2020

andrewvc requested changes May 11, 2020

View reviewed changes

bmorelli25 self-requested a review May 12, 2020 15:58

justinkambic added 7 commits May 12, 2020 13:50

Refresh existing docs images.

4193330

Add tls-related images.

54a2058

Add certificates page to docs.

08b7b92

Update settings page with explanation of cert threshold fields.

b07b278

Add placeholder image of updated settings page. Will need finalized v…

f22f935

…ersion of this after we merge updated defaults for age limit threshold.

Add new alerting docs page.

c2e0b25

Refresh settings page image.

2ecbbfd

justinkambic force-pushed the uptime_7.8-docs-images branch from fad4c40 to 2ecbbfd Compare May 12, 2020 17:51

bmorelli25 reviewed May 12, 2020

View reviewed changes

justinkambic added 3 commits May 12, 2020 14:19

Implement feedback and re-write/simplify some sections.

24ff319

Clean up words.

d46a503

Implement feedback on sentence structure.

141c28e

bmorelli25 reviewed May 12, 2020

View reviewed changes

justinkambic added 3 commits May 12, 2020 16:45

Improve copy on alerting page.

0495751

Improve copy on settings page.

4a63705

Update layout on alerting page.

f0a0de9

justinkambic requested a review from andrewvc May 13, 2020 13:41

Merge branch '7.8' into uptime_7.8-docs-images

16a903e

bmorelli25 approved these changes May 21, 2020

View reviewed changes

Merge branch '7.8' into uptime_7.8-docs-images

05af11e

justinkambic merged commit f0765f3 into elastic:7.8 May 26, 2020

justinkambic mentioned this pull request May 26, 2020

[Uptime] 7.8 docs (#66118) #67335

Merged

		For example, you may want to make sure that none of your organization's TLS certificates have been
		valid for longer than one year. This is becoming a common security requirement. Modifying the `Age limit`

	For example, you may want to make sure that none of your organization's TLS certificates have been
	valid for longer than one year. This is becoming a common security requirement. Modifying the `Age limit`
	For example, a common security requirement is to make sure that none of your organization's TLS certificates have been valid for longer than one year. Modifying the `Age limit`

Conversation

justinkambic commented May 11, 2020

Summary

Checklist

For maintainers

Uh oh!

elasticmachine commented May 11, 2020

Uh oh!

andrewvc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinkambic commented May 12, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinkambic commented May 12, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinkambic commented May 15, 2020

Uh oh!

EamonnTP commented May 21, 2020

Uh oh!

justinkambic commented May 26, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants