Skip to content

Add docs for Slack integration #2815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jun 1, 2020
Merged

Add docs for Slack integration #2815

merged 13 commits into from
Jun 1, 2020

Conversation

mapsandapps
Copy link
Contributor

@mapsandapps mapsandapps commented May 21, 2020

Ticket is SVC-60.

localhost_2222_guides_dashboard_slack-integration html (1)

Copy link
Member

@jennifer-shehane jennifer-shehane left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a few changes:

  • I added an image of what the Slack notifications look like.
  • I added instructions as bullet pointed lists.
  • Clarified some places where I didn't know how to click into the config (mostly clicking into Configure from within Cypress).
  • Added existing images for how to navigate to Org Integrations + Project Integrations.
  • I updated an outdated photo/instruction in GitHub integrations also.

Let me know if any of my updates are out of line with how the Dashboard will intend to function due to any updates.

Copy link
Contributor

@CypressCecelia CypressCecelia left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add this to the features listed in Dashboard Introduction like we do for GitHub here?
https://docs.cypress.io/guides/dashboard/introduction.html#Integrate-with-GitHub

Additional comments on individual lines. First time doing the line suggestions, hopefully they're ok 😬

trydionel
trydionel previously approved these changes May 26, 2020
@jennifer-shehane jennifer-shehane dismissed stale reviews from trydionel and themself via 9e5cb0f May 26, 2020 15:16
@jennifer-shehane jennifer-shehane self-requested a review May 26, 2020 15:33
CypressCecelia
CypressCecelia previously approved these changes May 27, 2020
@trydionel trydionel self-requested a review May 27, 2020 15:37

1. Select your organization in the organization switcher.
{% imgTag /img/dashboard/select-cypress-organization.png "Select an organization" width-600 %}
1. Select the project you wish to integrate with a GitHub repository.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is referring to GitHub. Where did that come from?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was a mistake from copying over from GitHub doc, since we have the same steps for entering the Integrations pages.

@trydionel
Copy link
Contributor

I don't love the screenshots that were added here, and the step-by-step instructions seem overly specific to the current implementation. Given that the goal of Dashboard documentation has been to focus on what's possible with a given feature, what's the rationale behind tieing the documentation so tightly to the current presentation?

@CypressCecelia
Copy link
Contributor

Given that the goal of Dashboard documentation has been to focus on what's possible with a given feature what's the rationale behind tieing the documentation so tightly to the current presentation

From a support perspective, having more detailed docs should reduce the number of questions/issues that users have.

I wasn't aware that the goal of Dashboard documentation is to provide a light overview of the features (as compared to Test Runner). If this is the case, would it be possible to retain the more detailed documentation internally at least? It's helpful to know all the nuts/bolts when supporting these features.

@jennifer-shehane
Copy link
Member

I was also not made aware of any new strategies pertaining to how the docs are written in terms of Dashboard features.

I agree with @CypressCecelia about the step by step being helpful to users we interact with.

When I review docs written for Dashboard features, I sit down and follow them to see if I can do what they say. Having never looked at Slack integration before, I got stuck at some points. Mostly where it would generically say "Configure your Slack", which was not clear where to go.

I also recognize the challenges of documenting a web application in general, where screenshots go out of date and would love to have someone full time to own our docs in order to address these issues more broadly.

@jennifer-shehane jennifer-shehane dismissed stale reviews from CypressCecelia and themself via f4f0a75 May 28, 2020 06:01
@trydionel
Copy link
Contributor

I'd thought we were on the same page about the goal of the Dashboard docs, apologies. Since I'm taking ownership of the Dashboard docs, I'm going to spend some time in the coming weeks on clearly defining a strategy and direction for these docs -- what we want to cover, how we can best maintain them, and how to find the balance for detailed walkthroughs vs upkeep cost. Watch for a document on that soon.

In the meantime, we can ship with the detailed walkthrough and screenshots for now. We're releasing on Tuesday, so I'd like to get this out into the wild by Monday.

@trydionel trydionel self-requested a review May 29, 2020 14:07
trydionel
trydionel previously approved these changes May 29, 2020
@trydionel
Copy link
Contributor

Actually, one tweak -- can we replace the Slack image with this? :)

Screen Shot 2020-05-29 at 10 44 55 AM

@jennifer-shehane
Copy link
Member

Update image
Screen Shot 2020-06-01 at 9 11 03 PM

@trydionel trydionel self-requested a review June 1, 2020 17:21
@amirrustam amirrustam merged commit f991fc9 into develop Jun 1, 2020
amirrustam added a commit that referenced this pull request Jun 2, 2020
Add docs for Slack integration (#2815)
@matthamil matthamil deleted the add-slack-integration branch April 14, 2021 19:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants