Skip to content
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

Overhaul identity docs #2814

Closed
wants to merge 8 commits into from
Closed

Overhaul identity docs #2814

wants to merge 8 commits into from

Conversation

akeller
Copy link
Member

@akeller akeller commented Oct 30, 2023

Description

Adjustments covering internal feedback and open issues in the Identity docs, including:

Missing pieces include a "why" or a concrete example. Being more opinionated or concrete helps users learn and work with Identity quickly. This includes:

  • Realistic user roles or group names (examples - business analysts, system analysts, architects, support, developers, etc.)
  • Realistic permissions and authorization depending on the role or group name
    • In my experience in large IT organizations, a business analyst couldn't modify anything outside of the BPMN and would have read-only access.

Out of scope:

When should this change go live?

  • This change is not yet live and should not be merged until {ADD_DATE} (apply hold label or convert to draft PR)?
  • There is no urgency with this change.
  • This change or page is part of a marketing blog, conference talk, or something else on a schedule.
  • This functionality is already available but undocumented.
  • This is a bug fix or security concern.

PR Checklist

  • I have added changes to the relevant /versioned_docs directory, or they are not for an already released version.
  • I have added changes to the main /docs directory (aka /next/), or they are not for future versions.
  • My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
  • My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

@akeller akeller added component:identity Issues related with Identity project component:docs Documentation improvements, including new or updated content labels Oct 30, 2023
@akeller akeller self-assigned this Oct 30, 2023
title: "Installation and first steps"
sidebar_label: "Installation and first steps"
description: "Learn more about installing Identity, accessing the UI, default users, the home screen, and more."
title: "First steps"
Copy link
Member Author

Choose a reason for hiding this comment

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

This is only an introduction to initial configuration and UIs after logging in with demo demo. All installation instructions were moved.

@akeller akeller requested a review from dlavrenuek October 30, 2023 18:40
@@ -21,6 +23,9 @@ Navigate to [localhost:8080](http://localhost:8080) to see the UI exposed by Ide

The configuration in this guide creates an example user during installation; use this account to log in:

<!-- Is this true for any setup? -->
<!-- For setting up production systems, we should nudge users to remove this configuration prior to launching. -->
Copy link
Member Author

Choose a reason for hiding this comment

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

Copy link
Contributor

Choose a reason for hiding this comment

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

The demo user is included in the helm charts (it seems that this is the default case). Therefore it would make sense to also have it documented in the helm installation part of the docs. What do you think?

Copy link
Member Author

Choose a reason for hiding this comment

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

Interesting - we should surely mention that the demo/demo user is created by default in the Helm chart.

Do we need this page, then? Could we consolidate it with the "What is Identity" page and walk through what screens are available in the Identity UI?

@akeller akeller changed the title initial changes and comments Overhaul identity docs Oct 30, 2023
@akeller akeller added the hold This issue is parked, do not merge. label Oct 30, 2023
@akeller
Copy link
Member Author

akeller commented Oct 30, 2023

image

Do we have any data on what most users would need to do? Let's order this by "popularity".

For example, I would do the following:

  • Making Identity production ready
  • Configure logging
  • Connect to an existing Keycloak instance
  • Configure an external identity provider

@akeller
Copy link
Member Author

akeller commented Oct 30, 2023

@christinaausley I was working with @dlavrenuek on #2630 and decided to just open a PR using an approach I've seen you do - adding comments to the PR directly for collaboration.

I'm not sure how much you'll be able to add with the questions I've asked, but I wanted to include you early for awareness.

@@ -5,11 +5,7 @@ sidebar_label: "Incorporate applications"
description: "Use Identity to create an application and assign a permission to an application."
---

In this guide we will show you how to use Identity to create an application and assign a permission to an application.

:::tip Want to learn more about applications?
Copy link
Member Author

Choose a reason for hiding this comment

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

I removed this and used an in-line link in the sentence above since we have a caution admonition right below it.

@akeller
Copy link
Member Author

akeller commented Oct 30, 2023

@dlavrenuek I left a mix of comments, changes, and commented questions in this PR. Can you have a look?

- Public

Public and confidential applications are applications where a user can log in, like a custom Tasklist.
Copy link
Contributor

Choose a reason for hiding this comment

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

Good opportunity to link to both Tasklist and service worker documentation in the case users aren't familiar.

@akeller akeller requested a review from felix-mueller November 2, 2023 16:02
@akeller
Copy link
Member Author

akeller commented Nov 2, 2023

@felix-mueller are you able to answer some of the questions in this PR or provide concrete examples?

@akeller
Copy link
Member Author

akeller commented Dec 12, 2023

@dlavrenuek @felix-mueller how do you want to handle this moving forward? I can move questions into an epic, chunk up this PR into smaller increments, or close it. Some of this is covered by https://camunda.slack.com/archives/C064WFE0MV1/p1702317421204349.

How can I support collaborative improvements here?

@dlavrenuek
Copy link
Contributor

@akeller apparently I did not notice that I was mentioned in this thread where my input was required, which is very unfortunate. Since I will be away for a longer time starting next week, I would like to let @felix-mueller handle the the prioritization on our side.

@akeller
Copy link
Member Author

akeller commented Feb 13, 2024

Closing this as stale. Will continue smaller projects to improve Identity docs.

@akeller akeller closed this Feb 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component:docs Documentation improvements, including new or updated content component:identity Issues related with Identity project hold This issue is parked, do not merge.
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

3 participants