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

Spike: research user documentation approaches #195

Closed
brainwane opened this issue Jun 21, 2017 · 8 comments
Closed

Spike: research user documentation approaches #195

brainwane opened this issue Jun 21, 2017 · 8 comments

Comments

@brainwane
Copy link
Contributor

@brainwane brainwane commented Jun 21, 2017

We need user documentation that goes beyond just describing the system's capabilities. This issue is for a spike in which Sumana researches where & in what format(s) we should put that documentation within the application repo.

The user documentation should, per 4.5.1. "User Documentation" in the Approaches document:
• Include guidance specific to each type of user (e.g., providers, administrators, service agents, auditors);
• Accurately reflect capabilities the PSM provides, and avoid implying capabilities it does not (e.g., editing business rules in a GUI);
• Prepare users by providing a process overview for each major task they want to perform (e.g., determining someone’s eligibility, editing a user) and informing them of what to expect at each stage (e.g., how long each step might take, what expected output will look like);
• Predict common problems and suggest troubleshooting steps;
• Direct users to communities and resources for further help.

Users will need a combination of in-app context-sensitive help (in the form of hover text, pop-up explanations, and captions), standalone prose tutorials or manuals illustrated with screenshots, and a living community of practice to ask for help and clarification, and to make suggestions for improvements.

The standalone prose tutorials will be substantially the same for all installations across the US, and should be stored and maintained in the core Git repository and distributed as part of the live help system. We should also provide a standalone copy of the stock standalone prose tutorials on its web site, ensuring that there is a version accessible to the general public (without requiring a login).

@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Jun 21, 2017

  • In-app context-sensitive help
    • This depends on the frontend libraries and frameworks we use; James suggested it would be nice if we could in some way reuse stuff from a central knowledge base. Read the Docs content embedding via JavaScript might be something to consider.
  • Community of practice
    • The psm-dev mailing list and the #opentechstrategies IRC channel on Freenode, at least for now, comprise our community of practice. In the longer run, we might want to point people to StackOverflow (or run our own site using one of the FLOSS clones of StackOverflow/StackExchange) to provide a richer community of practice.
  • Standalone prose tutorials
    • We'll want to store those in some format like Markdown or rST within the repository and then display them via an in-app Help section, and serve them up at a standalone website that's open to the public internet. We could use a readthedocs.io domain, or a self-hosted Sphinx server, or a github.io site, or a similar automated document rendering and display application.
@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Jun 21, 2017

There exists a help topics system within the PSM as it is, but it does not work even on the reference implementation (that is, administrators cannot add help topics that are then viewable by other users). So for standalone prose tutorials, knowledge base articles, or similar material, we'll either need to make the help topics system work or replace it.

@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Jun 21, 2017

I suggest that the next thing we play with is a toolchain involving javasphinx, Sphinx, ReadTheDocs, and content embedding from RTD using JavaScript.

@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Jul 7, 2017

Among the user documentation we need to write: help documentation for admins. This includes both system admins and service admins (see the difference between these user types).

Topics they'll need to understand include:

  • System admins

    • The difference among user roles
    • Connecting PSM login to another authentication system
    • Troubleshooting when people can't self-register
    • Troubleshooting when people can't log in
    • Which user information is required versus optional
    • Which user information the user can modify or delete, and which user information the system admin can modify or delete
  • Service admins

    • How to use the enrollment verification process
    • Which enrollment information the provider or service agent can modify or delete, and which enrollment information the service admin can modify or delete
    • How to find out more about the PSM's risk assessment rules
    • Which federal or state data sources the PSM is checking for each submitted enrollment
    • What the provider will see/receive when enrollment is pending, modified, approved, or rejected
    • The difference between an agreement and an addendum
    • How to create, edit, and delete provider types
    • How the screening schedule works
    • How to view license/certification files (e.g., PDFs -- suggest desktop programs for user to use)
@jasonaowen
Copy link
Contributor

@jasonaowen jasonaowen commented Jul 12, 2017

There exists a help topics system within the PSM

I reviewed the help system in more depth today. We already knew it was incomplete; users cannot see help items admins create. Finishing that implementation is possible, but may not be the most effective use of our time.

The help system stores its help items (as it calls them) in the database. This allows for admins to create, edit, and delete topics at runtime. This may be useful for state-specific topics, but topics that all states need would have to be included in the seed data.

Seeding help items is fine, but such seeded help topics are not great for contextual help: we should be careful about providing a help link next to, say, a disclosure question that goes to a dynamic help page - admins could accidentally delete it, thinking it unnecessary in their environment, and be unable to restore it; there are few things more frustrating than clicking on a help link and receiving a 404 error. If we're seeding the data, and hardcoding links, it would be simpler to just write contextual help directly instead of building and using our own custom CMS.

On the other hand, maybe it really is useful to allow each state to customize its help documentation, and it is worth hardening pre-seeded help items against deletion. If we're providing separate docs for providers and admins, we would also want to build access controls around help topics. This is doable; we have examples of similar pages and patterns in the application.

@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Jul 21, 2017

See #238 (comment) re: the interplay between our user documentation toolchain choices & our templating language choices.

brainwane added a commit to brainwane/psm that referenced this issue Jul 28, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate revising this commit or adding a commit to wire the
Sphinx build process into our Gradle build process.
brainwane added a commit to brainwane/psm that referenced this issue Jul 28, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate revising this commit or adding a commit to wire the
Sphinx build process into our Gradle build process.
brainwane added a commit to brainwane/psm that referenced this issue Aug 2, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate revising this commit or adding a commit to wire the
Sphinx build process into our Gradle build process.
brainwane added a commit to brainwane/psm that referenced this issue Aug 2, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate that a next step will be wiring the
Sphinx build process into our Gradle build process.
brainwane added a commit to brainwane/psm that referenced this issue Aug 2, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate that a next step will be wiring the
Sphinx build process into our Gradle build process.
brainwane added a commit to brainwane/psm that referenced this issue Aug 2, 2017
This commit is related to SolutionGuidance#265 and SolutionGuidance#195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate that a next step will be wiring the
Sphinx build process into our Gradle build process.
slifty added a commit that referenced this issue Aug 8, 2017
This commit is related to #265 and #195. It includes a document
answering questions PSM system administrators will likely have,
`admin-help.rst`. It also includes some infrastructure for using
Sphinx to build the `.rst` file into an HTML file.

To test this:

$ pip install sphinx
$ psm-app/docs/userhelp/
$ make html

Then you should be able to see
`psm-app/docs/userhelp/build/html/admin-help.html` in your browser.
https://docs.readthedocs.io/en/latest/getting_started.html is a good
guide to how I'm using Sphinx here.

I anticipate that a next step will be wiring the
Sphinx build process into our Gradle build process.
@cecilia-donnelly
Copy link

@cecilia-donnelly cecilia-donnelly commented Aug 30, 2017

@brainwane, do you think this can be closed? We've now written the user documentation (yay!).

@brainwane
Copy link
Contributor Author

@brainwane brainwane commented Sep 8, 2017

Thanks, @cecilia-donnelly. I have split the issues and questions arising from this spike into their own issues, and am now closing this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.