-
Notifications
You must be signed in to change notification settings - Fork 0
docbug guidelines
The number one guideline that I can't express enough here is to look through the documentation to see if it's documented before asking the technical writer. The content is constantly changing, and you never know the content might be there.
IMPORTANT If a DocBug is submitted without the required details, the technical writer will reject and reassign the bug back to the reporter for more details. A DocBug description is incomplete without the Expected Behavior. It is necessary to outline what the user should expect.
Use tags to help the technical writer filter through the docbugs.
- DocBug (if anything, this one must be included)
- user-admin-guide
- troubleshooting-guide
- deployment-guide
Required field
[DocBug] {descriptive title}
[DocBug] Clarify the Dashboard roles for User Admin and Sec Admin
[DocBug] _{descriptive title}_
Required field
- Update content (Once we have the online help deployed, you'll be required to provide the link to the user/admin guide topic that requires updating.)
- New content ("New" means the feature has been implemented for some time, but we don't have anything documented yet. It means it's a missed document deliverable that needs to be fixed. It could also mean that we need to document, for example, troubleshooting steps for deployment issues.)
- User/Admin guide
- Deployment guide
- Troubleshooting guide
{A brief summary of the bug, mostly within 60 words or below. Make sure your summary is reflecting on what the problem is and where it is.}
- Update content
- New content
- User/Admin guide
- Deployment guide
- Troubleshooting guide
User guide should reflect the new behavior of the Portal Dashboard for User Admin and Security Admin
[ ] Update content
[ ] New content
---
[ ] User/Admin guide
[ ] Deployment guide
[ ] Troubleshooting guide
_{A brief summary of the bug, mostly within 60 words or below. Make sure your summary is reflecting on what the problem is and where it is.}_
Required field
- Behaves as designed
- Unexpected design behavior
- Known issue
- Known limitation
{Explain the expected behavior - be as specific as possible. Not putting anything here isn't helpful. Remember that we're talking about the "user journey ."Are they experiencing what they expected to in the app or not? If not, then this is where we document that information.
If this is an "unexpected design behavior" (isn't typical or logical), indicate why it behaves this way. This information helps the technical writer add the proper messaging to the documentation, reducing the number of support calls.
If this is a known issue or known limitation, the writer also needs to know this. If this is the case, indicate whether there are plans for a fix or if any workarounds should be documented. If there are workarounds, complete the Workaround field.}
- Behaves as designed
- Unexpected design behavior
- Known issue
- Known limitation
The Dashboard shows different information for different roles.
For User Admin and Security Admin, it will show data across the entire company EXCEPT for the Pending Requests (only requests sent to the current user are displayed, i.e. Admin will not see any other pending requests for any of the users).
- [ ] Behaves as designed
- [ ] Unexpected design behavior
- [ ] Known issue
- [ ] Known limitation
_{Explain the expected behavior - be as specific as possible. Not putting anything here isn't helpful. Remember that we're talking about the "user journey ."Are they experiencing what they expected to in the app or not? If not, then this is where we document that information._
_Also indicate if this behavior is "as designed ."If this is an "unexpected design behavior" (isn't typical or logical), indicate why it behaves this way. This information helps the technical writer add the proper messaging to the documentation, reducing the number of support calls._
_If this is a known issue or known limitation, the writer also needs to know this. If this is the case, indicate whether there are plans for a fix or any workarounds should be documented. If there are workarounds, complete the **Workaround** field.}_
Optional field
Provide attachments to help explain the issue better or supplement the Description. For example, if you have a Word document with the information necessary to resolve this DocBug, attach it to the bug or provide the SharePoint link.
Optional field
If there is a workaround that the user should know about, then put it here to be appropriately documented.