Criteria Clarification: Basics (Documentation)

[caelooney]

The project MUST include reference documentation that describes its interface.

Not all projects include an interface, as some are just GitHub repos without a website dedicated to downloading the software. I think that including a "N/A" option for projects (such as dotenv) which don't have an interface to describe would provide better clarification on this specific criteria point.

[david-a-wheeler]

Huh? That has nothimg to do with it. The interface is however other programs are supposed to access the program while it is running. If it is a library, what is the library API? If it is a web application, what URLs does itrespond to? If it is an application, How is it involked and what are the options?

[caelooney]

That makes a lot more sense. The front end developer in me went straight to anything "user interface" related. Thanks for the clarification!

[david-a-wheeler]

Any suggested wording to make it clearer?

[caelooney]

Possibly word it like this:

This project MUST include reference documentation that describes it interface. This can include descriptions for URL responses, API integrations, or the external interface.

And potentially provide a link to the CII Best Practices Interface section as an example?

I would imagine that if I am getting confused by what exactly is meant by a description of the interface, others might also so providing an example gives them an easy to view way of seeing if anything in their documentation is comparable.

[david-a-wheeler]

That's a reasonable start! I think some more specifics might help.

This project MUST include reference documentation that describes its interface, such as its application program interface (API).
Details: There must be documentation on how an end-user or developer would use it. If it is a library, document the major classes/types and methods/functions that can be called on them. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required.