Update docs about how Pulp Docs work

Author: pedro-psb

README.md

@@ -6,6 +6,5 @@ It leverages mkdocs plugin system to build and publish a single website from a v
 Here are some useful resources to help you get started:
 
 * [Basic Installation and Usage](https://pulpproject.org/pulp-docs/docs/dev/tutorials/getting-started/)
-* [Pulp Docs Architecture](https://pulpproject.org/pulp-docs/docs/dev/reference/architecture/)
+* [Understanding Pulp Docs](https://pulpproject.org/pulp-docs/docs/dev/reference/architecture/)
 * [Mkdocs/Markdown Cheatsheet](https://pulpproject.org/pulp-docs/docs/dev/reference/markdown-cheatsheet/)
-

docs/dev/index.md

@@ -1,10 +1,6 @@
-# Overview
+# Welcome to Pulp Docs
 
-Pulp-Docs is a tool for serving and building the Pulp Project documentation
-(see [The new Pulp "Unified Docs"](https://hackmd.io/eE3kG8qhT9eohRYbtooNww?view)).
+Pulp-Docs is a tool for serving, building and publishing the Pulp Project documentation.
 
-The idea is that after installing `pulp-docs`, you'll imediatelly be able run the unified website and preview local changes as they will appear in this site.
-Also, this is used for the production build.
-
-To start using it, see the [Getting Started](site:pulp-docs/docs/dev/tutorials/getting-started/) section.
-Before contributing, we recommend reading about the [Architecture](site:pulp-docs/docs/dev/reference/architecture/).
+See the [Getting Started](site:pulp-docs/docs/dev/tutorials/getting-started/) section to learn how setup and use `pulp-docs` cli in your development workflow.
+If you want to contribute or simply understand how it works, we recommend reading the article [Understanding Pulp Docs](site:pulp-docs/docs/dev/reference/architecture/).

docs/dev/reference/architecture.md

@@ -1,18 +1,61 @@
-# Architecture
+# Understanding Pulp Docs
 
-The Pulp Docs tool is a python package that provides a cli named `pulp-docs`.
-At it's core, it's an mkdocs plugin that extends from `mkdocs` cli by leveraging `click` composable features.
+This page explains some core design and concepts of the Pulp Docs tool.
 
-At it's based of `mkdocs`, it uses it's event/hook system to perform various manipulations to the build process,
-such as the selection of components to use, the construction of the navigation and the creation of dynamic pages.
+## Architecture
 
-The aggregation system works over a specific set of Pulp components.
-This set is defined in the `PulpDocs` plugin section of `mkdocs.yml` file, which contains the basic configuration required for it to be a member.
+The Pulp Docs tool is a python package that provides a cli, which we'll refer as `pulp-docs`.
+At it's core it's an mkdocs plugin, which we'll call *PulpDocs* from now on.
+Also, it extends from `mkdocs` cli by leveraging `click` composable features.
 
-With this set in place.
-To perform the aggregation, the `mkdocs.yml` specifies which Pulp components are considered members
+The main configuration file for the system is the Pulp Docs's `mkdocs.yml` file, which is the mkdocs entrypoint.
+Through that, the *PulpDocs* plugin is registered and can act on the building process to perform various interventions, like the selection of components to use, the construction of the navigation and the creation of dynamic pages.
+The main mechanism used for such interventions is the mkdocs's event/hook API.
 
-## Further Reading
+As mentioned, the `pulp-docs` cli extends `mkdocs` cli.
+The extra features it provides are also based on the PulpDocs plugin definition in the `mkdocs.yml`.
+
+To be an effective part of the PulpDocs website, a component must satisfy two requirements:
+
+1. Be registered as a *PulpDocs* component in the `mkdocs.yml`
+1. Contain `docs/` directory following the [Pulp Docs Content Structure](#pulp-docs-content-structure)
+
+The registration is centralized and it includes essential information of a component, like how to fetch it, what kind of component it is and how to display it's name.
+
+## Pulp Docs Content Structure
+
+The structure is based on Diataxis principles, where content is supposed to satisfy a specific [Persona](#persona) on one of the [Basic User Needs](#basic-user-needs).
+Although not Diataxis doesn't enforce a specific structure, currently *PulpDocs* requires content to fit into a strict directory tree.
 
-- [Mkdocs Plugins](https://www.mkdocs.org/dev-guide/plugins/#developing-plugins>) - Mkdocs Plugin system is the backbone of Pulp Docs.
+This structure is used for building the navigation.
+
+```bash
+docs/
+  user/
+    guides/
+    learn/
+    reference/
+    tutorials/
+  admin/
+    guides/
+    learn/
+    reference/
+    tutorials/
+  dev/
+    guides/
+    learn/
+    reference/
+    tutorials/
+```
+
+## Concepts
+
+* <a id="pulpdocs-plugin" href="#pulpdocs-plugin">PulpDocs</a>: The Pulp Docs mkdocs plugin.
+* <a id="persona" href="#persona">Persona</a>: A theoretical user with a specific set of needs.
+* <a id="basic-user-needs" href="#basic-user-needs">Basic User Needs</a>: The 4 categories that expresses the need of aquisition/application of skills and the cognition/action aspect of that need: Tutorial, How-To-Guide, Explanation, Reference. See <https://diataxis.fr/compass/>.
+
+## Further Reading
 
+- [Mkdocs Plugins](https://www.mkdocs.org/dev-guide/plugins/#developing-plugins>) - Understand how an Mkdocs Plugin plugin work.
+- [Diataxis](https://diataxis.fr/start-here/) - Understand the underlying principles for organizing content
+- [The new Pulp "Unified Docs"](https://hackmd.io/eE3kG8qhT9eohRYbtooNww?view) - Original design document for this project