Hi All!
As we’re getting closer to breaking out more addons into their individual repositories, we’d like to get a community take on our documentation organisation and structure.
We have 3 main categories in the https://ayon.ynput.io docs. Artist, Admin and Developer. Up to here all is good I believe. But with more public contributions to the docs, we need to set a more formal structure about what should go where.
We’re pretty much talking about settings mostly. Currently we have category for settings that has subcategories, and then each addon can have it’s own “usage” docs in various places.
My take would be to unify this so that each Addon can (but doesn’t have to) have it’s page in each of the main sections. Artists, Admin, Dev.
Artist docs: Solely information related to how to use and benefit from the addon. Tutorials, guides, explanations from user perspective. No configuration, apart from explaining artist choices presented to them.
Admin docs: Configuration and details about all the individual functions of the addon from a structural and technical perspective. Each addon feature should describe what it’s for and how it’s configured.
Dev docs: Any developer caveats and info needed to expand the addon functionality with code customisation.
If we keep this rigid structure for each addon, we can make sure it’s easier to navigate, but also eventually store the markdowns of the docs in the addon repository and add a simple CI/CD process that would update the main docs pages when docs are merged in the addon PR. It will also make it easier to distribute the responsibilities for maintaining the individual addon docs.
There’s probably always going to be a bit of confusion and it’s visible already in the PR that are being created here where most of them are for purely settings, hence duplicating some information already documented in the other integration sections. Pull requests · ynput/ayon-documentation · GitHub
Any idea and opinion on how to best structure the docs is more than welcome. In the meantime we’ll unify to per addon categorisation so we have at least a good place to start.