Project

Profile

Help

Task #2348

Generate structure of Pulp 3.0 Documentation

Added by amacdona@redhat.com about 3 years ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
Normal
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

0%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Documentation
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 11

Description

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:
https://etherpad.net/p/Pulp_3.0_Docs_Structure

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

Associated revisions

Revision 1814f3fd View on GitHub
Added by Austin Macdonald almost 3 years ago

Create 3.0 docs framework

Creates the basic structure of the documentation that will go out with
3.0.0. This also moves all the old docs so that they can be moved as
necessary.

re #2348
https://pulp.plan.io/issues/2348

Revision 5fe42455 View on GitHub
Added by Austin Macdonald almost 3 years ago

Create 3.0 docs framework

Creates the basic structure of the documentation that will go out with
3.0.0. This also moves all the old docs so that they can be moved as
necessary.

re #2348
https://pulp.plan.io/issues/2348

Revision 5fe42455 View on GitHub
Added by Austin Macdonald almost 3 years ago

Create 3.0 docs framework

Creates the basic structure of the documentation that will go out with
3.0.0. This also moves all the old docs so that they can be moved as
necessary.

re #2348
https://pulp.plan.io/issues/2348

Revision 5fe42455 View on GitHub
Added by Austin Macdonald almost 3 years ago

Create 3.0 docs framework

Creates the basic structure of the documentation that will go out with
3.0.0. This also moves all the old docs so that they can be moved as
necessary.

re #2348
https://pulp.plan.io/issues/2348

History

#1 Updated by amacdona@redhat.com about 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 amacdona@redhat.com about 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.

#3 Updated by semyers about 3 years ago

  • Groomed changed from No to Yes

#4 Updated by mhrivnak about 3 years ago

  • Sprint/Milestone set to 28
  • Tags Pulp 3 added

#5 Updated by semyers about 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. :)

#6 Updated by amacdona@redhat.com almost 3 years ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to amacdona@redhat.com

#7 Updated by mhrivnak almost 3 years ago

  • Sprint/Milestone changed from 28 to 29

#8 Updated by amacdona@redhat.com almost 3 years ago

  • Status changed from ASSIGNED to POST

#9 Updated by amacdona@redhat.com almost 3 years ago

  • Status changed from POST to MODIFIED

This wasn't automatically switched because I used re: in the commit message.

#10 Updated by bmbouter over 1 year ago

  • Sprint set to Sprint 11

#11 Updated by bmbouter over 1 year ago

  • Sprint/Milestone deleted (29)

#12 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#13 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF