This milestone develops and validates improvements to ORT’s reporting and documentation so that the extensive data it generates can be easier interpreted and acted upon by non-specialists. The work restructures how findings, such as known vulnerabilities, license matches, and package metadata issues, are aggregated, summarized, visualized, and explained in ORT’s Web App and public documentation. More of the information captured by ORT and user configurations will be included and transformed into clear, navigable summaries that reveal how results were derived and what options an user has to resolve found issues. Labels and curated information for packages will be added to ensure manual data corrections are visible to all users. Clickable license links in the Summary View will lead directly to their respective packages, and we will show the tools used to simplify debugging/reproducing issues. Documentation will be audited and reorganized using the Diátaxis framework, a well-known framework to organize and improve documentation by dividing content into tutorials, how-to guides, technical references, and explanatory sections. This restructuring will enable users to easily find the resources they need when required. For example, the new tutorials section will provide a step-by-step guide through the ORT workflow, covering everything from running a scan in CI/CD system, such as Forgejo, to resolving issues (licensing, vulnerability, technical) and generating a Software Bill of Materials. This work will significantly lower the learning curve and technical skills required to use ORT effectively for checking software projects and resolving identified issues.
This milestone develops and validates improvements to ORT’s reporting and documentation so that the extensive data it generates can be easier interpreted and acted upon by non-specialists. The work restructures how findings, such as known vulnerabilities, license matches, and package metadata issues, are aggregated, summarized, visualized, and explained in ORT’s Web App and public documentation. More of the information captured by ORT and user configurations will be included and transformed into clear, navigable summaries that reveal how results were derived and what options an user has to resolve found issues. Labels and curated information for packages will be added to ensure manual data corrections are visible to all users. Clickable license links in the Summary View will lead directly to their respective packages, and we will show the tools used to simplify debugging/reproducing issues. Documentation will be audited and reorganized using the Diátaxis framework, a well-known framework to organize and improve documentation by dividing content into tutorials, how-to guides, technical references, and explanatory sections. This restructuring will enable users to easily find the resources they need when required. For example, the new tutorials section will provide a step-by-step guide through the ORT workflow, covering everything from running a scan in CI/CD system, such as Forgejo, to resolving issues (licensing, vulnerability, technical) and generating a Software Bill of Materials. This work will significantly lower the learning curve and technical skills required to use ORT effectively for checking software projects and resolving identified issues.