...
- Determine to scope of Documentation Standard Task Force
- Collect information both externally and Internally
- Create Standards / Best Practices for Community
- Create Documentation Best Practice badging system.
- Internal:
Documentation
- The project MUST provide basic documentation for the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_basics]
Details:This documentation must be in some media (such as text or video) that includes: how to install it, how to start it, how to use it (possibly with a tutorial using examples), and how to use it securely (e.g., what to do and what not to do) if that is an appropriate topic for the software. The security documentation need not be long. The project MAY use hypertext links to non-project material as documentation. If the project does not produce software, choose "not applicable" (N/A).Rationale:Potential users need documentation so that they can learn how to use the software. This documentation could be provided via the project website or repository, or even via hyperlink to some external information, so we do not specify exactly where this information is.
- The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_interface]
Details:The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. 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. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so). Documentation of a REST interface may be generated using Swagger/OpenAPI. Code interface documentation MAY be generated using tools such as JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), and Doxygen (many). Merely having comments in implementation code is not sufficient to satisfy this criterion; there needs to be an easy way to see the information without reading through all the source code. If the project does not produce software, choose "not applicable" (N/A).
Other
- The project MUST provide basic documentation for the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_basics]
David Boswell
Hart Montgomery Arun S M Kamlesh Nagware – Thanks for your feedback and I see that you've each mentioned that having more resources at the graduated level would be helpful. Here are some ideas to consider, although it would also be really helpful to hear from people involved in projects about what additional help they'd be interested in.
- I think there is probably something around documentation and translation support for graduated projects that would be worth doing. If possible, perhaps we can make some budget available to bring in a technical writer, for example, to help with project docs?
- We could also make the resources available to Incubation projects time bound – for instance, an Incubation project could have a year to grow and mature and at the end of that time the TSC decides to either move it to Graduated or move it to the Labs.
- The project placement on the Hyperledger site does not currently provide a distinction between Graduated and Incubation projects since they're treated the same way now. We're looking at updating the site this year to give more prominent positioning to Graduated projects, so the priority placement item will become more of an incentive.
- The same is true of Workshops – this is a new concept so we have not yet seen the benefits to a project of running a workshop. After we've done a few of these we can analyze the outcome and if we can see a bump in users and contributors to a project after a workshop then this will become an incentive for Graduation status too.
External
Articles
https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f
...