Please Document the Insights Tracker

[mgifford]

Feedback summary

I'm interested in the component "Usage Insights" feature here:
https://github.com/openedx/paragon/tree/master/www/src/components/insights

I think that this could be extended and applied to other design systems.

Improvements

It is missing basic documentation over how it is used and what is being covered.

ChatGPT gave me this when I asked for a summary:

The "Usage Insights" feature in the Open edX Paragon library is designed to provide comprehensive documentation, examples, and analytics regarding the usage of Paragon's UI components, hooks, icons, and utilities within projects. This feature aims to enhance developers' understanding of how different elements of the Paragon library are utilized, promote best practices, and facilitate the integration of Paragon components into their applications. Here's a breakdown of the primary files related to "Usage Insights" and their purposes:

1. ComponentUsage.tsx

• This file likely documents how individual components are used within projects. It may include usage statistics, example implementations, and best practices for integrating components into applications.

2. ComponentUsageExamples.tsx

• Contains example implementations of components documented in ComponentUsage.tsx. This might include code snippets or live examples demonstrating how to use components effectively in various scenarios.

3. ComponentsUsage.tsx

• Similar to ComponentUsage.tsx, it might provide aggregated insights into the usage of multiple components across projects, highlighting popular components or common patterns.

4. HooksUsage.tsx

• Documents the usage of React hooks provided by the Paragon library. This could include insights into the most frequently used hooks, examples of hooks in action, and best practices for managing state and side effects in applications using Paragon.

5. IconsUsage.tsx

• Offers documentation and examples related to the use of icons within the Paragon library. This file might detail how to integrate icons into components, customize icon properties, and leverage icons to enhance UI design.

6. ProjectUsageExamples.tsx

• Provides examples of how the Paragon library is utilized within entire projects. This could showcase case studies or sample projects that effectively use Paragon components, hooks, and utilities.

7. ProjectsUsage.tsx

• Similar to ProjectUsageExamples.tsx, but may focus more on analytics and insights into the adoption of Paragon across various projects, highlighting trends in component usage and integration strategies.

8. SummaryUsage.tsx

• Presents a high-level overview of the usage of the Paragon library's features, summarizing the key insights from the detailed documentation and examples provided in the other files.

9. SummaryUsageExamples.tsx

• Complements SummaryUsage.tsx by providing concrete examples that illustrate the summarized usage insights, potentially offering a quick reference guide for developers.

10. UsagesList.tsx

• Likely a component that lists all the documented usages, examples, and insights, providing an easy navigation interface for developers exploring the "Usage Insights" feature.

11. UtilsUsage.tsx

• Focuses on the utilization of utility functions and helpers provided by the Paragon library. This file might include documentation on how to leverage these utilities to simplify development, improve performance, or enhance the user experience.

The "Usage Insights" feature serves as a valuable resource for developers working with the Paragon library, offering insights into the practical application of its components and fostering a deeper understanding of how to build effective and engaging user interfaces with Paragon.

[adamstankiewicz]

Hi @mgifford, thanks for raising this issue around Paragon's "Usage Insights"! The tool is available on the public Paragon documentation website under the "Tools" section in the menu navigation.

Here is a direct link: https://paragon-openedx.netlify.app/insights

---

The documentation that does exist for the "Usage Insights" today lives here: https://github.com/openedx/paragon/tree/master/dependent-usage-analyzer

tl;dr; dependent-usage-analyzer is intended to run on a daily cron to automatically clone dependent projects (manually curated, see here and here), and walks through an abstract syntax tree of all projects to determine whether an import is related to Paragon.

(Note, the automation of the "Usage Insights" tool is currently disabled as it's currently erroring when the associated GitHub Action runs. Hopefully that will be resolved sooner or later to ensure the tool is always showing the most up-to-date information.)

---

I think that this could be extended and applied to other design systems.

This is an interesting proposition. I would agree it could likely be abstracted out of Paragon into its own standalone library for serving other design systems, assuming the dependent projects (repositories) are known. I don't think it's solely relevant to design systems, either; it might apply to any JavaScript library that seeks to understand how its consumers (at least known dependent projects) use the library. In the Open edX ecosystem, a similar approach could theoretically apply to @edx/frontend-platform, @edx/frontend-lib-content-components, and @edx/frontend-lib-special-exams as well; right now, it's unclear exactly what exports are most/least commonly used in the other shared JS libraries across the Open edX platform).

It is missing basic documentation over how it is used and what is being covered.

The technical documentation is a bit lacking in detail, yes. However, the primary audience / consumer of the tool today has been for product delivery teams that consume Paragon, which primarily rely on the documentation website vs. reading/understanding the Paragon code (using the tool in the browser on the documentation website should become fairly evident how it's used and what it covers.

That said, I think both aspects of documentation could still be improved as it related to Paragon:

• Ensure the "Usage Insights" tool (and perhaps other tools, like the "Playground") more discoverable/prominent on the documentation website.
• Ensure the "Usage Insights" has more detailed technical documentation for the technical audience.