docs(compliance-forms) update guide for creating form via UI #11936
Conversation
datahub-cyborg
bot
added
the
needs-review
docs/api/tutorials/forms.md
Outdated
|
|
||
| Documentation Forms are a way for end-users to fill out all mandatory attributes associated with a data asset. The form will be dynamically generated based on the definitions provided by administrators and stewards and matching rules. | ||
| Compliance Forms are a way for end-users to fill out all mandatory attributes associated with a data asset. The form will be dynamically generated based on the definitions provided by administrators and stewards and matching rules. |
There was a problem hiding this comment.
Compliance Forms are not about "end-users" filling out requirements- end users don't care!
They'd prefer to NOT be filling out requirements.
Instead, Compliance Forms are a way to crowd source critical governance and compliance attributes across your data assets AT SCALE. Our target end user if a Data Governance/Compliance Leader, not the end user. We need to ensure we are always speaking about empowering them, first and foremost. They are the persona we need to click with on this
There was a problem hiding this comment.
Updating to use the copy you suggested here https://github.com/datahub-project/datahub/pull/11936/files#r1866766843
| 2. Completing a Form for a single Asset or multiple Assets (DataHub Cloud only) | ||
| 3. Understanding different Form Question completion states | ||
|
|
||
| The example uses the **Governance Initiative 2024**, a Verification Form with 3 Required Questions: |
There was a problem hiding this comment.
This doc seems to change format completely, being fully example driven. I would consider either running with that narrative through the entire doc series, with a single Form as the example, or just ditching it and keeping it consistent about how to complete
docs/features/feature-guides/compliance-forms/complete-a-form.md
Outdated
Show resolved
Hide resolved
docs/features/feature-guides/compliance-forms/complete-a-form.md
Outdated
Show resolved
Hide resolved
docs/features/feature-guides/compliance-forms/complete-a-form.md
Outdated
Show resolved
Hide resolved
docs/features/feature-guides/compliance-forms/complete-a-form.md
Outdated
Show resolved
Hide resolved
|
|
||
| When completing a Compliance Form, you may encounter various types of questions, each with unique completion states based on existing metadata or prior user responses. This section highlights these scenarios to help you understand how questions can be answered, confirmed, or updated during the process. | ||
|
|
||
| **_1. What is the primary use case for this asset?_** |
There was a problem hiding this comment.
I almost feel like this type of Example based switch would be more part of a Tutorial, as opposed to a Feature Guide
docs/features/feature-guides/compliance-forms/complete-a-form.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Create and Assign a Compliance Form from the DataHub Cloud UI | ||
|
|
||
| ### Prerequisites |
There was a problem hiding this comment.
I really like how you have these pre-requisites etc. I don't see that on the Complete a Form side. It would be good to spell out the prerequisites to being able to complete a form as well
There was a problem hiding this comment.
@jjoyce0510 the only prereq for completing a form is that it's assigned to you, correct?
Should we also call out that users need Edit privileges?
There was a problem hiding this comment.
The main thing I'm interested to get consistent is the example narrative.
What I've done before is had a running example but always discuss it after the cold-hard crisp step.
For example:
Creating a Form
From the navigation bar, head to Govern > Compliance Forms. Click + Create to start building your Form. From here you can give the form a name, description, and a type.
- name:
- description:
- type:
For example, imagine I were creating a Compliance Form to track PII across all my Snowflake Tables. Perhaps I would name the form "" with a description ""
......
And then I'll just subtely continue that journey with the user AFTER each cold hard step is defined. Might be worthwhile to consider this as the format to make both create a form and complete a form docs consistent
datahub-cyborg
bot
added
needs-review
datahub-cyborg
bot
added
pending-submitter-merge
and removed
needs-review
Checklist