[Pulp-list] Docs Organization Proposal

[Brian Bouterse]

A couple of thoughts:

I'm glad you brought this up. This is something we need to do! I think reorganizing these docs is important to do as part of 2.6.0 because in 2.6.0 we switched from using two sphinx [0][1] projects to one [2]. That change caused the left side to look completely different so we should reorganize 2.6.0 so that its still usable even though its all in one sphinx project now.

Once we do get the design worked out, I think either a story should be written or a bug made. If it is a bug then it should be put on a 2.6.0 or a story should be put into the Dec sprint.

I think this work should be focused on reorganization. Some of the pages below are clearly marked about which existing page will become a given new page but many are not. Could the other ones be marked about where the content will come from? If there are new sections that you do want to write, can you mark them as such also. This would probably be easier to edit in an etherpad. Want to move the next version there so we can edit out of one document?

Previously we've used a folder level organization of the docs that cleanly separates "user" and "developer". Is the idea to also reorganize the file layout to match the top level headings you are proposing?

Also a question about the index structure below. I imagine the structure below would be represented on the left side of the homepage navigation and the homepage index. Is that correct?

About the User Guide. Is it just the one entry that when clicked on shows a page like [3], or are the subheadings in [3] also shown on the homepage index?

This is a great start, and I appreciate you starting this effort. I think some more planning would be benefit this, but that's just my opinion.

[0]: http://pulp-user-guide.readthedocs.org/en/latest/
[1]: http://pulp-dev-guide.readthedocs.org/en/latest/
[2]: http://pulp.readthedocs.org/en/latest/
[3]: http://pulp.readthedocs.org/en/latest/user-guide/index.html

-Brian

----- Original Message -----
> From: "Austin Macdonald" <amacdona at redhat.com>
> To: pulp-list at redhat.com
> Sent: Tuesday, November 18, 2014 1:46:17 PM
> Subject: Re: [Pulp-list] Docs Organization Proposal
> 
> 
> On 11/18/2014 11:09 AM, Randy Barlow wrote:
> 
> 
> 
> In short, this:
> 
> - User Guide
> - Developer Guide
> 
> would become this:
> 
> - User Documentation
> - Administrator Documentation
> - Integrator Documentation
> - Contributor Documentation
> Since we have combined the projects there is some information that I think
> belongs on the root level. This is the structure that I have in mind:
> 
> 
> 
>     * Index
> 
> 
>         * What is pulp?
>         * How to use these docs:
> 
> 
>             * Explanation of the layout
>         * links to documentation of plugins
> 
>     * User Docs
> 
>     * Integration Docs
> 
>         * REST API
>         * Events
>         * Pulp Nodes
>         * Conventions
> 
> 
>     * Contributor Docs
> 
>         * Index
> 
> 
>             * high level information
>             * checklist
>         * Contributor Setup (formerly develop setup)
> 
>             * script install instructions for the lazy
>             * setup
>             * configuration
>         * Branching and Merging (maybe combined)
>         * Contributing documentation
>         * Policies
>         * Plugin Blueprint (Formerly Implementing Support for New Types)
>         * Building Pulp for a Release (Formerly Building Instructions)
>         * Troubleshooting
> 
> 
>             * add database migration
>             * add a sample restart script
> 
> 
>     * Troubleshooting (moved from user docs)     * Glossary (moved from user
>     docs)
> 
> _______________________________________________
> Pulp-list mailing list
> Pulp-list at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-list