Problem
Discovery and findability of research (such as findings reports) and accessibility documentation is difficult for both the internal team and the public for multiple reasons:
- Multiple Sources of Truth: Research artifacts are scattered across platforms: wiki, repositories, and Google Drive, making it hard to know where to look. Finding documentation may get harder as we roll out more products (i.e. Core, Elements) and documentation becomes even more scattered.
- Finding specific information in the wiki (for example, research for a specific component) is difficult since they are buried in findings reports. Creating an intuitive IA in the wiki is also challenging.
- It is difficult to update the website (presumably the most intuitive platform for users to access research) so we don't do it often with new research findings.
Proposed solution
Create a docs repository for all research and accessibility documentation to be centralized.
We are hoping this centralized documentation will help by:
- Having one place as a source of truth across products (Elements, Core).
- Updating the site with research and accessibility documentation could be more automated. If we can update the site in an easier way, we can improve discoverability, findability, and availability of research that is shared with the public.
- We may be able to improve documenting research findings in a modular way and help users find all research on a specific component, but it depends on the capabilities of the repo and how we set it up.
Next steps
Get started by experimenting with a new “docs” repo to centralize research and accessibility documentation.
- Coordination with accessibility to align as we set it up
- Review examples of other repos that use the GitHub markdown file approach
- Review tutorials for how to work with GitHub markdown files and using tags and metadata
- Ideate on the folder structure and file naming conventions we might use
- Publish a study as a file to get familiar with the mechanics
- Explore how to use metadata/labels to improve automation and findability.
- Identify the mechanics of how updates might get automatically made to the site
- Further refine the structure and process of publishing research in markdown files as we learn more
- Make a decision and recommendation about whether or not we should move forward with using the docs repo and markdown files.
Definition of done for this MVP phase:
We have created a skeleton folder structure and published at least one research report and possibly other artifact types in the repo. We have made a determination if we want to further pursue using the docs repo for our centralized documentation needs.
Problem
Discovery and findability of research (such as findings reports) and accessibility documentation is difficult for both the internal team and the public for multiple reasons:
Proposed solution
Create a docs repository for all research and accessibility documentation to be centralized.
We are hoping this centralized documentation will help by:
Next steps
Get started by experimenting with a new “docs” repo to centralize research and accessibility documentation.
Definition of done for this MVP phase:
We have created a skeleton folder structure and published at least one research report and possibly other artifact types in the repo. We have made a determination if we want to further pursue using the docs repo for our centralized documentation needs.