# Better Pulp documentation Objective: Pulp plugin documentation contains everything a Pulp user needs to set up and operate anything related to that plugin. ## 2022/01/25 Melanie: If we return to Ina's question from the end of last week and take a feature of the upcoming Pulpcore release, how would we approach documenting it? Ina: Each plugin is independent and autonomous. Plugins require compatibility releases. Perhaps docs are added as part of the compatibility release for the plugin? Brian: We should look at some short term objectives first, like implementing the CLI in our documentation. We have all these CLI commands but are not passing them on to our users. Ina: We need a clear definition of a long-term goal. From what we have now, it isn't clear how the CLI action item has any relation to what we want to achieve overall. Fabricio: I'm interested in working to improve the docs overall, especially the installation docs. The CLI objective makes less sense as an immediate step. ### Docs goals long & short term Problem statement: Pulp users get things done in spite of our docs. We undoubtedly lose and confuse potential users along the way. Overall goal: Move towards having full workflow documentation and compatibility statements within each plugin doc. Short term goal: There are a number of steps we need to identify to achieve these goals. In terms of an immediate, short term goal, while our CLI options have been developing, many plugin docs have not been updated. The CLI greatly lowers the barrier of entry for users when compared with scripting against the API. Ask at Open Floor that one person from each mini team reviews the plugin docs, and replaces all API calls with CLI where applicable. ## 2022/01/18 ### Attendees Brian, Fabricio, Ina, Melanie Plugin sites: key steps to doing everything Melanie: * On average, over 90% of open source community members make their first contribution to project docs. * Pulp's contribution process for docs requires a running Pulp instance or [Grant's hack](https://github.com/ggainey/pulp_startup/commit/913707cd125c79dc693194c96d0a0828eafb0ba1) * mcorr has no experience or familiarity with .rst, has no Pulp dev instance, and finds it an awful effort to preview changes * Some components use mkdocs, which has a much nicer format and is much easier to preview Long term goal would be to move to mkdocs and simplify the previewing process, therefore making it easier to contribute in general. Brian: * First steps: * simplify the Pulpcore docs lefthand navigation * plugin docs become menu items in docs.pulpproject.org's lefthand nav * pulpcore docs start to fade to the background Melanie: * Happy to help with ^ but the contribution process is such overkill and limited experience with .rst Fabricio: * Will look into building a container image with minimal plugins so that docs can be changed and previewed easily Ina: * How verbose should every plugin be? Brian: * User should be able to do everything they need to do for their whole life on that one docs site * Should be able to live on the plugin site forever and ever Melanie: * this will lead to a lot of duplicate content Brian: * We will have less duplicated content than we think, for example here are some common divergences: * sync workflow- different plugins don't support mirrored, some don't take different parameters etc * all plugins should support streamed and on demand but others don't * some use publications, some of them don't * are these things really the same? The installation documentation is the same largely the same. Ina: * how to avoid duplicate content? * most of the plugins are installed in the same way * if there is some specific step one plugin would need, have one unique doc * if we put all the installation docs into the plugin docs * treat the installer docs as shared Brian: * we need a cultural shift in Pulp docs * we think of pulpcore as a place we drop off our docs introducing a feature rather than its implementation in a plugin workflow Ina: * any new feature implemented in core - how much of the docs are included in Core vs Plugin?