Generate structure of Pulp 3.0 Documentation
The documentation has grown organically alongside Pulp and structural problems with the documentation have made it difficult to keep the docs up to date.
The goal of this task is to collaboratively generate the tree structure that will form the framework of the 3.0 documentation. It is not necessary to determine the entire structure exactly, the intention is to agree on broad strokes.
Determining where all the information in our current docs fit into this structure is explicitly not a part of this work.
The "hacking out" phase of this will happen in this etherpad:
Please keep the discussion here, and use the etherpad to track the "current" plan. For more complex conversations, please post a result of the discussion.
This Task will be complete when:
- 2.x docs are moved to docs_old (only on the 3.0-dev branch)
- A docs structure is generally agreed upon
- new docs are stubbed out
#1 Updated by firstname.lastname@example.org over 3 years ago
I would like to see a lot of attention on the developer docs early on. One of the things that the Django project has done very will is that their internal docs are a sort of constitution for how the project is meant to run. https://docs.djangoproject.com/en/1.10/internals/ We have discussed a "one stop shop" for process, and I think this is where it should be. If we give some extra thought to the structure now, the internal docs might become more central to our process.
The good news is that a lot of the Django docs (particularly internal) are structured in a general way that I think we could borrow, making this much less work than if we had to do it from scratch.
It is likely that a lot of the User Guide organization may need to wait until we have more development, and that is ok. If adding more structure feels contrived or premature, it should wait.
#2 Updated by email@example.com over 3 years ago
- Sprint Candidate changed from No to Yes
There was some discussion on IRC about the root structure, here is a summary.
We have 3 types of users, CLI users, REST API users, and Contributors, and these should each be in the root.
One principle discussed is that other sections that apply to more than one user type may also be considered for root status. We specifically discussed the Installation section and determined that Contributors will use developer-install docs and REST API users don't need to install Pulp, they just need access to the API. Therefore, Installation will live in the CLI user docs area.
#5 Updated by semyers over 3 years ago
Something that has arisen out of discussion of this is that a landing page that helps guide users where they need to go will be very helpful, and can also help to link between sections.
For example, while the installation of the pulp server and CLI is specific to a CLI user, and setting up a dev environment is specific to a contributing user, both tasks are useful to a REST API user, since both can potentially give a REST API user a working API to integrate with. A bit of text along the lines of "REST API Users looking to integrate with Pulp can get a working API server by either <a>installing pulp</a> or <a>setting up a development environment</a>."
As an aside, I'd also like to state that all three identified classes of user are users. I'm trying to adjust the language I use accordingly, so "CLI User" instead of "Pulp User", "REST API User" or "Integrating User" instead of "Integrator", "Contributing User" instead of "Contributor" or "Developer". Contributors are users, too. :)
Please register to edit this issue