reference-coverage-tester [WIP]

A tool to test the documentation and sample coverage for DocFX YML files. This tool is designed by and for the Office Platform content team (OP Content) to measure the effectiveness of the reference documentation in office-js-docs-reference and office-scripts-docs-reference.

Purpose

Currently, the primary purpose of this tool is to measure sample coverage. OP Content has the philosophy that developers prioritize API reference documentation and samples. By ensuring the two are found together, we provide higher educational potential.

The output the tool is a .csv file. The data should be aggregated in a way that shows meaningful coverage against a well-defined success metric. In OP Content, we weight the API pages against their page views to determine high-value samples and sample opportunities.

Contributions and maintenance

Contributions are welcome. The current scope is one team and two repos. The documentation there has some level of customization, so improvements to this tool would need to keep that in mind.

Understanding the CSV file

Each row of the CSV has these values: Class,Field,Type,Description Rating,Has Example?

• Class: The name of class, interface, or enum.
• Field: The name of the property, method, or enum field. "N/A" represents the row for the class description.
• Type: What category of class or field this is.
• Description Rating: An automated evaluation of the JSDoc description quality. Could be "Missing", "Poor", "Fine", or "Good". "Deprecated" is given if the @deprecated tag is found.
• Has Example?: A boolean of whether there is example code associated with this API.