Standardize documentation approach for package authors

[joshrosso]

Describe the problem/challenge you have

Package authors need a means of providing shipping documentation alongside their package. Ideally, the documentation source could live alongside the package itself such that it could be consumed and rendered in a variety of location. By providing specification or standards for package docs, we could ensure any package could be supported in a variety of catalogs, docs sites, tooling etc.

Consider the following example:

In the above, docs are stored inside the repo bundle. This could also enable docs to be rendered in a variety of ways, including air-gapped environments.

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible" 👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

[danielhelfand]

An additional note here that was briefly discussed:

• Autogenerating documentation (Should there be a tool to autogenerate docs in such a way that promotes a consistent documentation format but still allows flexibility for users)

One issue that might come up in this discussion is duplication of docs (i.e. does a Package author need new docs if there are no new changes worth documenting). Should there be a more centralized way of maintaining docs? My personal opinion is that I am okay with duplication of docs as a means of making sure the docs are always available with the Package. But would be curious to hear other thoughts on this.

Additionally, we should come up with a documentation convention for Packages as mentioned in the issue. Should there be a dedicated docs folder containing all documentation. What are important pieces of information that each piece of documentation should have?

Think this issue would be really worthwhile and could see a lot of different efforts coming out of it.