Refactor Information Architecture of Documentation section

As far as ownership/maintainership goes, maybe there needs to be another content type called something like Documentation Guide Group, which doesn't convey maintainership, but is only used for navigation, and maybe doesn't have a node body but just the summary field?

Another possibility would be that we continued to list all of the maintained top-level guides on /documentation, but have them grouped into categories more like what is listed here than what is currently suggested on #2828874: Design top level landing page for the new documentation system... This really kind of feels like a duplicate of that issue to me, by the way.

Thanks to everyone who has contributed so much work on revising Docs IA, and for the years of work put into the Docs in general! Naturally, Docs are a major element of the project.

That said, I'm sure everyone who turns to Docs will be glad to learn a major revision of the IA is underway. As things stand, finding things via nav is often tough-to-impossible for long-time users, and (based on anecdotal evidence) discouraging to new users.

I agree with the statement that parts of the proposed outline in the summary above are quite well organized, and that others need more thought. It would be helpful to break out details like how decisions will be made, how assumptions will be tested, what timeline can be envisioned, what constraints are in place and similar planning concerns. Perhaps there's an upcoming call?

Interested to learn more, and to understand how folks can ramp up their related contributions.

Acknowledging that there are several things to address before we can truly determine the final IA, here's a quick iteration on the proposed breakout, since it was occurring to me as I read the issue summary. It attempts to tighten groups/sequences, use parallel constructions (main headers starting with verbs; second level headers excluding verbs) and to suggest a few new headers to cover. Noting it purely for discussion and further improvement.

1. Understanding Drupal 8
   1. Drupal version numbers
   2. Drupal conventions
   3. Configuration management
   4. Site administration
2. Installing & updating Drupal 8
   1. System requirements
   2. Installation profiles
      1. Standard
      2. Minimal
      3. Umami: Drupal 8 demonstration installation profile
   3. Multisite
   4. Updates
3. Extending Drupal 8
   1. Modules
      1. Core modules
      2. Contributed modules
      3. Custom modules
      4. Drupal 7 module conversion
   2. Themes
      1. Core themes
      2. Contributed themes
      3. Custom themes
      4. Drupal 7 theme conversion
   3. Libraries
      1. External libraries in core
      2. Additional third-party libraries
   4. Distributions
      1. Contributed distributions
      2. Custom distributions
   5. APIs
4. Migrating to Drupal 8
   1. From other systems
   2. From earlier version of Drupal
5. Building accessible sites
6. Building mobile sites
7. Building multilingual sites
8. Managing site performance and scalability
9. Maintaining security
10. Testing
    1. PHPUnit
    2. Behat
    3. Nightwatchjs
    4. Continuous integration

It's great that this is being thought about! Both the outline in the issue summary and the one in #4 seem like good starts... but... We need to make sure that people coming to /documentation with a specific question or task in mind, with varying levels of knowledge (from "I know nothing" to expert", or with certain skills, or that are a certain fraction of the way towards building the site they want with Drupal (which could be zero), can find the information they need fairly quickly. I don't think that either of the outlines was designed with any of these in mind... Maybe the first thing to do would be to step back and write out some user stories or personas and think about what types of information people will need to find, and make an outline that ensures that information can be found, rather than starting with the information we have and trying to organize it so it makes more sense?

For example, the outline in #4 especially, and to a lesser extent the one in the issue summary currently, are a mix of developer documentation and adminstrator documentation, which I think is a mistake. For instance, developers who want to write a module would need to go to Extending > Modules > Custom modules, Extending > APIs, and Testing sections (at least) to find all the information they might need, plus the Developer docs landing page (where they would find version-independent docs on things like Git, conding standards, how to deal with projects on drupal.org, etc.). I don't think the outline here would help them find that information very well?

Also I don't think fits too well the tasks an administrator would need to do. For instance, Configuration management is up in the "understanding" section, but it's not all "understanding" but also a lot of how-to I think? And if you use a distribution (under Extend currently), you actually have to start with that when you install, not add it afterwards.

So... Could we perhaps start over by thinking about what information people need to find, or we want them to find, and then go from there to define an outline and information architecture?

Completely agreed, @jhodgdon, that personas have to be a top consideration in this effort to revamp docs IA. I also agree strongly that we need to define and follow a process vs throwing out proposed solutions. The process you sketch matches my thinking, though I have different recommendations on a few baseline IA decisions.

(I hesitated to post the outline in #4 since that post muddies my support for defining and following a process, and I shouldn't have jumped ahead even with an iteration. Since my noodling around has become a part of the conversation, I'll leave it there vs undoing history to correct my mistake; I hope it won't be a distraction.)

As for how to accommodate the different personas within the IA, I would advocate mixing them and adopting a single, topic-based outline. I agree with the points in #5 about looking hard at where things should go. Also, I believe the downsides to a single topic outline were right to raise, and that they can be mitigated.

The discussion of whether to adopt a single topic outline or several based on individual personas will be an interesting one. Would folks agree it's more complex than can be handled in the issue queue? It's certainly not a polemic, and treating it as one would be counterproductive. I'd be interested in a work session to hammer out the various related decisions and strike the best available balance.

Ideally without tipping the discussion into polemic it's still possible to share some reasons I advocate mixing personas (an approach we pursue with success in OwnSourcing training materials and recommendations to clients). The overarching principle is that in a software project, the perspective of each persona must always mesh with the other personas' perspectives, whether a reader is part of a team or a solo solution provider. The better these perspectives mesh, the better the outcomes. By extension, collocating perspectives helps address some important considerations:
- fostering understanding across disciplines vs reinforcing silos of knowledge, somewhat lessening burdens on readers to explore each silo and work out the intersections between roles.
- improving use of docs as reference materials (in addition to their function as onboarding materials), somewhat lessening burdens on readers to know which role 'owns' a piece of information then find it in each silo.
- exposing all users to the same overall organization of the docs, somewhat improving colleagues' ability to point each other to relevant material.
Collocating perspectives also lessens some authoring and maintenance challenges, as authors can more easily consider closely related information when it is in the same place.

Naturally, mixing personas when addressing a given topic also has downsides that need attention, and will involve tradeoffs. There are good examples for inspiration, such as role-based filters to show just the relevant content according to a user's choice (similar to the commonly used selector for software version). Our adoption of course depends heavily on the technical constraints of d.o., but I believe we can reasonably review what others are doing with combined roles and see what solutions we can pursue.

No matter what choices this initiative makes, there is complexity to address. Do people feel there is value in discussing these choices in an online working session?

I'm not advocating separating out personas completely. What I'm advocating is starting by defining what types of people are seeking what types of information that would be under "Drupal 8 Documentation", then making decisions about the outline that will make it fairly easy for all of them to find the information they're seeking. So, let's start by defining the differnt "personas" who are seeking information in the Drupal documentation.

I did a similar exercise of people/seeking for the Community/Contribute section recently in a spreadsheet format -- it's in the third tab of this sheet:
https://docs.google.com/spreadsheets/d/1vbIdtL-HAPK3bqiCamRIak048fcEqaWP...

And we already have a "Documentation Pain Points spreadsheet:
https://docs.google.com/spreadsheets/d/1IM1a6WDS9x8WJRX3VLvGLlIa93hbsgQ-...

So I added a second tab there called "Personas seeking..." where we can start this exercise. Anyone who would like to edit either sheet, PM me in Slack or use the drupal.org contact form to send me the email address you use in Google, or within that sheet, request access if you know how to do that. Or, we can do this exercise in some other manner... this is just a suggestion and I put a few rows in there to start.

Thanks for the links in #7, @jhodgdon, and the work that went into them.

I'll rough together a quick sketch of process/timeline to post here, if others agree that appears to be a good next step. It might facilitate inviting others' input. I'm also happy to reach out to anyone needing to know what's up and point them to this thread.

Retitling issue and adding clarification to issue summary because this seems to be about the IA of /documentation not just /docs/8. Change back if not.

Just a reminder that the current IA is intentionally flat and wide instead of narrow and deep. #2744915: Define new structure for documentation

Last time we did user research into how people used documentation on Drupal.org the deeply nested navigation was problematic. So with the new documentation system, and when things were migrated into it, we made the choice to try and flatten things a bit. That doesn't mean we can't use hierarchy like in the examples above, but I do think we we should be careful not to do to much.

Keeping things relatively flat can also help with the fact that we've got numerous personas to account for. Lots of different people coming to the documentation for a lot of different reasons. Keeping it flatter allows people to more quickly scan what is available and find what they are looking for with fewer clicks.

There are some personas for Drupal.org users here https://www.drupal.org/drupalorg/personas, they're a bit generic, but I think they're probably still useful for something like this issue. In the past we've often said that the goal of pages like /documentation, and docs/8 was to help people who are in the "Learner" persona, with the ultimate goal of transitioning them to the "Skilled" persona. But, allowing those in "Skilled", or above to still be able to quickly find the reference information that they may need from time-to-time.

Also, FWIW, we can probably achieve any groupings we want using the existing guide/page architecture. You can nest a guide inside of another guide in order to create groupings like those shown in the proposed outline. Unless I'm not understanding the concerns about permissions for sub-guides?

Next steps were to:

- Get feedback on this proposal: I think Kay's suggestion in #4 is a nice improvement, but I also agree w/ the comments from JH in #5, and Joe as well.

Next step suggestion: Can someone make a proposal for a draft that addresses these 3 needs expressed by the group by EO next week?
1) Keep the IA relatively flat, but reduce a bit so it's not so big because this corresponds to persona needs
2) Don't mix admin needs and site building needs so much -- users will search for things differently
3) Consider persona actions for high-level nav to help users drill-down quickly

- Discuss governance strategies that allowed for community ownership but also protects against inflated IAs
^ It sounds to me like we've discussed strategies for the IA itself, but not yet talked about how we will manage it. Any ideas?
Here's my 2 cents:
1) Review the DWG acceptance criteria for any proposed changes and change process [Link]
2) Changes should be submitted via ticket for review by DWG and other stakeholders
3) DWG appoints a reviewer who considers the proposal w/ in a specified time frame, and makes a recommendation to the DWG
4) DWG decides and posts a response to proposals should be made w/ in the ticket by the DWG delegate
5) Changes to IA are implemented by DWG delegates, other changes are managed by the team or individual working on the project.
6) Docs are peer-reviewed for accuracy and coherency by DWG delegates and/or other volunteer stakeholders.
7) Final versions are merged into the existing documentation IA or conctent.
8) Change log updated to reflect decision-making bkg on the initiative page [Link to change log]
(just a suggestion, I saw the comment from joe and thought -- hmm, this would be good to know more generally.)

- Contact Guide Maintainers about guide ownership and contribution once we have come up with a governance strategy

^ anyone else we need to speak w/ who is not yet on this ticket?

- Coordinate with Drupal.org about above governance and if it's possible to fix this problem on the site with solutions we are proposing
TBD :)

- Remaining tasks to be updated

Thanks for the summary @svettes. I'd suggest that we limit the scope of this issue to the IA only. Governance issues should be discussed separately.

I'd like to propose a revision of @svette's next steps.

Next Steps

1. Identify the persona(s) that we're targeting in the Community Guide.
2. Determine what information these personas need from the Community Guide.
3. Propose new high level IA, taking into consideration:
   • Needs of targeted personas.
   • IA should not be too narrow and deep.
4. Map existing content to IA, identifying gaps and content that should be merged or removed.

I'll take a quick stab at starting that work here.

Identify the persona(s) that we're targeting in the Community Guide.

@jhodgdon I see that you have 8 personas listed in the documentation pain points doc and 21 personas listed in the Getting Involved content audit. There are then 5 separate personas listed on the Drupal.org personas page. This feels like too many personas to keep in mind while drafting documentation.

What if we chose the 3 most common personas and targeted those in our IA restructure?

Looking at the documentation pain points doc, I see varying skill levels of the following personas listed:

1. Site Builder
2. Themer
3. Programmer

Proposal: Let's use these 3 personas to drive the IA of the Community Guide. Following @eojthebrave's suggestion, let's focus of speaking to the "learners" for each of these personas with the goal of making them "skilled". I.e., our audience consists of learner site builders, learner themers, and learner programmers.

There are also the following in the documentation pain points doc:

1. Evaluator
2. Bug reporter
3. New contributor

These are important, but I'd imagine that they require only a small handful of persona-specific pages. So, perhaps they should not majorly influence top level IA?

Determine what information these personas need from the Community Guide

Borrowing again from documentation pain points doc, I propose to following "needs" for the 3 identified personas:

1. (learner) Site Builder. Installation, site building, tutorials, how to pick a version of Drupal. Workflow & deployment tutorials. How to add particular features to a site (news/blog section, forums, commerce, etc etc etc).
2. (learner) Themer. Theming documentation.
3. (learner) Programmer. Step by step documentation on how to write modules. Introduction to API docs, coding standards if they might contribute it back to drupal.org eventually. Example code.

Propose new IA

Iterating on #4. Please provide feedback on this revision:

Installing Drupal
    - System Requirements
    - Installation Profiles
        - Core profiles
        - Contributed profiles (distributions)
Updating Drupal
    - Updating Drupal core
    - Migrating to Drupal 8
        - Drupal 7 module conversion
        - Drupal 7 theme conversion
Extending Drupal
    - Modules
        - Core modules
        - Contributed
        - Creating custom modules
    - Themes
        - Core themes
        - Contributed
        - Creating custom themes
    - Libraries
Developer Resources
    - Security
    - Performance and scalability
    - Testing
Build Guides
    - Multilingual guide
    - Mobile guide
    - Accessibility guide

• I've omitted API docs since those aren't actually part of the community guide.
• I've also omitted sections that don't seem immediately relevant to our identified personas.
• Regarding breadth, I think this is a reasonable number of top level menu items. We can also display the top 2 levels by default to make the structure more browsable, I think that's more of a UX issue.
• Admittedly the "build guides" section is a cop out.

After browsing the community guide more, I think we probably need to consider all 3 levels of the docs hierarchy in the IA redesign. There's a lot of cruft that needs to be cleaned up at level 3, and it would be great to have some general agreement about the approach for that cleaning. After a review of level 3 content, I have a few issues to raise for discussion that impact the IA.

I've created #2979430: Update "Online documentation structure" standards to facilitate IA refactoring to capture changes to our standards for online documentation structure.

Additionally, we should consider that there's a good deal of content that is duplicative of the Drupal 8 User Guide. What do we do with these guides and pages?

Installing Drupal 8 is a great example. I'd like to propose that we gut these redundant sections by removing all of the sub pages and linking directly to the user guide. The Installing Drupal 8 of the community guide doesn't appear to be providing any value IMO.

This also follows the published standards for Obsolete and Duplicated Documentation Pages,

If there are several pages with substantially the same information on them, they should be consolidated into one page with a redirect

In summary, I'd suggest that we adopt the following rules in our IA refactor:

• Remove pages from the Community Guide that largely duplicate content in the User Guide
• Require that a sub page be a minimum of 500 words. Otherwise, it should merged into another page that shares the same topic, or removed.
• Require a "guide" in the Community Guide require at minimum 3 sub pages. Otherwise, it should merged into anther guide or removed.

There are actually quite a bit of API docs in the community documentation - https://www.drupal.org/docs/8/api - these tend to be a bit higher level and more step-by-step (but not really tutorials ...) than what you find in the code documentation available on api.drupal.org. I do think we need a way to get people to these pages quickly, and account for them in the IA somehow.

I think it would be great if we could display the first 2 levels of the IA in the navigation, especially if the 1st level becomes largely containers/categories. Based on our experience at Drupalize.Me people seeking documentation have a preference for big lists they can scan quickly over either searching, or navigating a deep hierarchy.

I agree that narrowing things to a small list of personas is useful. And I think I'm fine with Site Builder / Themer / Developer intersected with the learner/skilled/expert as being those personas.

I agree that we should remove content that is largely duplicative of the user guide.

Installing Drupal 8 is already mostly pointing to the User Guide so replacing it with 1) just a link to the user guide and maybe 2) a link to an upcoming quick guide sounds very good - easy call. (The only unique part is step 3 - "Create a database". The User guide doesn't explain how to do it at all and I think that is right.)

It's much more interesting to discuss Updating Drupal 8 compared to the same topic in the user guide - and the upcoming quick guide. (Before Composer, using Drush, the quick guide was "drush up drupal" - good old days ;-) )

I think it is a mistake to use the drupal.org personas on https://www.drupal.org/drupalorg/personas as a basis for IA. I think it is better to think in terms of user stories and make sure everyone looking for particular types of documentation can quickly find it, which is why I proposed more "personas" (which is probably not the right word).

I think it is a mistake to use the drupal.org personas on https://www.drupal.org/drupalorg/personas as a basis for IA.

Agreed. I consider those as descriptions of skill levels rather than personas. The personas that I'm positing are "Site Builder / Themer / Developer". I used these when designing the IA in #16.

I'd love to keep the conversation focused on the IA. E.g., is something missing from the IA that these personas need? @eojthebrave has suggested adding links to high level API docs. Noted.

Does anyone have any other specific suggestions for changes to the IA described in #16?

Worth sticking the IA outline in a text file under version control, to more easily track suggestions / for future use?

Also - devil's advocate - how many of us have actually properly read all the persona stuff? (I haven't). Not sure how much the DA ultimately spent on it, but the budget specified in the RFQ was $45,000, and it looks like at least some of it is helpful.

This is the current IA. Top level items are out of order.

Understanding Drupal 8
- Overview
- Directory Structure
- Translation in Drupal 8
Understanding Drupal version numbers
- Which version of Drupal core should I install?
- Which version of contributed modules, themes, and translations should I install?
- When is the next release?
- Which version of Drupal am I running?
- Which version of a module or theme am I running?
- What about upgrading and backwards compatibility?
- Drupal release versions
- Development snapshots
- What do version numbers mean on contributed modules and themes?
- What are alpha and beta releases, and release candidates?
- Release stable version
- Drupal release history
Cron automated tasks
- Cron automated tasks overview
Installing Drupal 8
- Before a Drupal 8  installation
- Step 1: Get the Code
- Step 2: Install dependencies with composer
- Step 3:  Create a database
- Step 4: Configure your installation
- Step 5: Run the installer
- Step 6:  Status check
- Trusted Host settings
- Quick-start: launch a local demo version of Drupal 8 using 4 brief steps
Configuration management
- Changing the storage location of the sync directory
- Workflow using Drush
- File system based workflow
- Workflow using the Drupal UI
- Managing your site's configuration
- Keeping Your Local and Remote Sites Synchronized - Drupal 8
System requirements
- Browser requirements
- Web Server
- Limitations of 32-bit PHP
- Database requirements
- PHP requirements
- Database server
Extending Drupal 8
- Installing modules' Composer dependencies
- Installing Drupal 8 Modules
- Overview
- Installing Themes
- Interface guidelines (Seven admin theme)
- Finding Contributed Modules
- Uninstalling Modules
- Installing Modules from the Command Line
- Updating Modules
- Module Documentation and Help
- Troubleshooting
- Module Configuration
- Installing Sandbox Modules
Administering a Drupal 8 site
- Automated Cron
- Internal Page Cache
- Getting started with Drupal 8 administration
- Managing content
- Working with content types and fields
- Working with content types and fields
Migrating to Drupal
Multisite Drupal
- Multisite Drupal 8 considerations
- Multisite Drupal 8  Setup
-  Multisite folder structure in Drupal 8
- Drupal 8 Multisite on a LAMP stack
Contributed modules
- Default Content
- Varbase Editor
- Business Rules
- Youtube Gallery
- Permissions by Term
- Block Style Plugins
- Developer Suite
- Commerce Braintree
- Feature Toggle - Deprecated
- Socialfeed
- HelloSign
- [marked for deletion]
- Marketing Cloud
Accessibility
- Drupal 8 Accessibility Features
- Contributed Modules for Extending Accessibility in Drupal 8
- Hide content properly
- External Accessibility Resources
Updating Drupal 8
- Update core via Composer
- Updating Drupal 8 - overview of options
- Update core manually
- Update core via Drush
- Update modules
Upgrading to Drupal 8
- Upgrade using Drush
- Preparing a site for upgrade to Drupal 8
- Upgrade using web browser
- Known issues when upgrading from Drupal 6 or 7 to Drupal 8
- Upgrading from Drupal 6 or 7 to Drupal 8
- Drupal 8 migrate modules
- Contributing to Migrate
- Learn key Drupal 8 concepts prior to upgrading
- Customize migrations when upgrading to Drupal 8
- Choosing the upgrade approach
Security in Drupal 8
- Writing secure code for Drupal 8
- Security of generated PHP files
- Secure configuration for site builders
- Secure Database Queries
- Drupal 8: Sanitizing Output
- US NIST Password Guidelines review
Mobile guide
- Responsive Images in Drupal 8
- Native mobile application development
- Mobile-specific website
- Web-based mobile apps
- Responsive web design
- Responsive Design + Server-side Components (RESS)
- Mobile testing tools
- Related mobile technologies
- Front-end performance
Multilingual guide
- Choosing and installing multilingual modules
- Translating configuration
- Translating content
- Install a language
- Enable language negotiation
- Menu translation in Drupal 8
'Clean URLs' in Drupal 8
- Fix Drupal 8 'Clean URLs' problems
Theming Drupal 8
- Defining a theme with an .info.yml file
- Drupal 8 Theme folder structure
- Adding Regions to a Theme
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
- Classy themes css selectors
- Including Default Image Styles With Your Theme
- Working with breakpoints in Drupal 8
- Including Part Template
- Preprocessing and modifying attributes in a .theme file
- Using attributes in templates
- Sub-theming: Using Classy as a base theme
- Creating a Drupal 8 sub-theme, or sub-theme of sub-theme
- Creating advanced theme settings
- Theming differences between Drupal 6, 7 & 8
- Drupal Twig conversion instructions (tpl.php to html.twig)
- Upgrading classes on 7.x themes to 8.x
- Sub-Theme inheritance
- Creating automation tools for custom themes (Gulpjs)
- How to edit ALT tag on your site logo
- Theming Overview: How data is displayed
- Z-indexes in Drupal 8
- Using CSS pre-processors
- Add Google Webmasters Tools verification meta tag via the .theme file
Managing site performance and scalability
- Content Delivery Network [CDN]
- Blazy
- Server Scaling
Creating custom modules
- Building a Views display style plugin for Drupal 8
- Creating a custom Field
- Create a custom field widget
- Create a custom field formatter
- Create a custom field type
- A practical guide to building basic Drupal 8 modules
- Testing
- Defining a Block
- Settings
- Theming
- Basic structure
- Prepare a Module skeleton
- Add a composer.json file
- Naming and placing your Drupal 8 module
- Let Drupal 8 know about your module with an .info.yml file
- Adding Custom Blocks to your custom Module
- Add a Default Configuration
- Use Config in Block Display
- Process the Block Config Form
- Add a Form to the Block Configuration
- Create a custom block
- A "Hello World" Custom Page Module
- Going further
- Add a menu link
- Add a routing file
- Adding a basic controller
- Create a custom page
- Getting Started - Background & Prerequisites (Drupal 8)
- Defining and using your own configuration in Drupal 8
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module
- Understanding Hooks
- Add module to drupal.org
- Event Systems Overview & How To Subscribe To and Dispatch Events
Drupal 8 APIs
- Runtime Assertions
- Installation & Setup Guide
- Configuration
Testing
- Converting D7 SimpleTests to Drupal 8
- Simpletest Class, File, and Namespace structure
- Types of tests in Drupal 8
- Javascript testing using Nightwatch
Converting Drupal 7 modules to Drupal 8
- Step 3: Convert hook_menu() and forms
- Step 2: Convert automated tests to Drupal 8
- Debugging Drupal 8 module upgrades
- Step 1: Convert mymodule.info to mymodule.info.yml
- Intro & Before you start: Setting up a Drupal 8 module dev environment
- Resources and tutorials
- D7 to D8 upgrade tutorial: Convert hook_menu() and hook_menu_alter() to Drupal 8 APIs
- D7 to D8 Upgrade: Generated HTML
- D7 to D8 upgrade: fields, widgets and formatters
- WSCCI Conversion Guide
- WSCCI Conversion Guide - Best practices
- WSCCI Conversion Guide - Pass 3
- WSCCI Conversion Guide - Pass 2
- WSCCI Conversion Guide - Pass 1
- D7 to D8 tutorial: pathinfo module
- D7 to D8 upgrade tutorial: Pants module
- Step 5: How to upgrade D7 variables to D8's state system
- Step 4: Convert Drupal 7 Variables to Drupal 8 Configuration
Creating distributions
- How to Write a Drupal 8 Installation Profile
Core modules and themes
- Basic structure of Drupal 8
Distributions
- deGov
- Thunder
- Install deGov 1.x
- Install deGov 2.x
- Upgrading from deGov 1.x to 2.x
Contributed themes
- Drupal8 W3CSS Theme Configuration
External Libraries in Core
- External PHP Libraries
- External JavaScript Libraries
- External CSS Libraries

Tried to order a bit, bring user items up, devel down. Developers lists can be more complex and collapsed even (developers being more tech savvy than a user, we don't need to keep everything in open for a dev like we do for a user).

 
Understanding Drupal 8
- Overview
- Directory Structure
- Translation in Drupal 8
- Core modules and themes (Basic structure of Drupal 8)

USER HELP

System requirements
- Browser requirements
- Web Server
- Limitations of 32-bit PHP
- Database requirements
- PHP requirements
- Database server

Installing Drupal 8
- Before a Drupal 8  installation
- Step 1: Get the Code
- Step 2: Install dependencies with composer
- Step 3:  Create a database
- Step 4: Configure your installation
- Step 5: Run the installer
- Step 6:  Status check
- Trusted Host settings
- Quick-start: launch a local demo version of Drupal 8 using 4 brief steps

Administering a Drupal 8 site
- Automated Cron
- Internal Page Cache
- Getting started with Drupal 8 administration
- Managing content
- Working with content types and fields
- Working with content types and fields

Extending Drupal 8
- Installing modules' Composer dependencies
- Installing Drupal 8 Modules
- Overview
- Installing Themes
- Interface guidelines (Seven admin theme)
- Finding Contributed Modules
- Uninstalling Modules
- Installing Modules from the Command Line
- Updating Modules
- Module Documentation and Help
- Troubleshooting
- Module Configuration
- Installing Sandbox Modules

Contributed modules (This is list of modules? Misleading?)
- Default Content
- Varbase Editor
- Business Rules
- Youtube Gallery
- Permissions by Term
- Block Style Plugins
- Developer Suite
- Commerce Braintree
- Feature Toggle - Deprecated
- Socialfeed
- HelloSign
- [marked for deletion]
- Marketing Cloud

Contributed themes
- Drupal8 W3CSS Theme Configuration

Distributions
- deGov
- Thunder
- Install deGov 1.x
- Install deGov 2.x
- Upgrading from deGov 1.x to 2.x

DEVELOPER HELP

Drupal 8 APIs
- Runtime Assertions
- Installation & Setup Guide
- Configuration

Theming Drupal 8 (Collapse or move extended list to a subpage)
- Defining a theme with an .info.yml file
- Drupal 8 Theme folder structure
- Adding Regions to a Theme
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
- Classy themes css selectors
- Including Default Image Styles With Your Theme
- Working with breakpoints in Drupal 8
- Including Part Template
- Preprocessing and modifying attributes in a .theme file
- Using attributes in templates
- Sub-theming: Using Classy as a base theme
- Creating a Drupal 8 sub-theme, or sub-theme of sub-theme
- Creating advanced theme settings
- Theming differences between Drupal 6, 7 & 8
- Drupal Twig conversion instructions (tpl.php to html.twig)
- Upgrading classes on 7.x themes to 8.x
- Sub-Theme inheritance
- Creating automation tools for custom themes (Gulpjs)
- How to edit ALT tag on your site logo
- Theming Overview: How data is displayed
- Z-indexes in Drupal 8
- Using CSS pre-processors
- Add Google Webmasters Tools verification meta tag via the .theme file

Creating custom modules (Collapse or move extended list to a subpage)
- Building a Views display style plugin for Drupal 8
- Creating a custom Field
- Create a custom field widget
- Create a custom field formatter
- Create a custom field type
- A practical guide to building basic Drupal 8 modules
- Testing
- Defining a Block
- Settings
- Theming
- Basic structure
- Prepare a Module skeleton
- Add a composer.json file
- Naming and placing your Drupal 8 module
- Let Drupal 8 know about your module with an .info.yml file
- Adding Custom Blocks to your custom Module
- Add a Default Configuration
- Use Config in Block Display
- Process the Block Config Form
- Add a Form to the Block Configuration
- Create a custom block
- A "Hello World" Custom Page Module
- Going further
- Add a menu link
- Add a routing file
- Adding a basic controller
- Create a custom page
- Getting Started - Background & Prerequisites (Drupal 8)
- Defining and using your own configuration in Drupal 8
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module
- Understanding Hooks
- Add module to drupal.org
- Event Systems Overview & How To Subscribe To and Dispatch Events

Configuration management
- Changing the storage location of the sync directory
- Workflow using Drush
- File system based workflow
- Workflow using the Drupal UI
- Managing your site's configuration
- Keeping Your Local and Remote Sites Synchronized - Drupal 8

Testing
- Converting D7 SimpleTests to Drupal 8
- Simpletest Class, File, and Namespace structure
- Types of tests in Drupal 8
- Javascript testing using Nightwatch

Understanding Drupal version numbers
- Which version of Drupal core should I install?
- Which version of contributed modules, themes, and translations should I install?
- When is the next release?
- Which version of Drupal am I running?
- Which version of a module or theme am I running?
- What about upgrading and backwards compatibility?
- Drupal release versions
- Development snapshots
- What do version numbers mean on contributed modules and themes?
- What are alpha and beta releases, and release candidates?
- Release stable version
- Drupal release history

Sequrity and Maintenance

- Security in Drupal 8
-- Writing secure code for Drupal 8
-- Security of generated PHP files
-- Secure configuration for site builders
-- Secure Database Queries
-- Drupal 8: Sanitizing Output
-- US NIST Password Guidelines review

- Performance and Scalability
-- Content Delivery Network [CDN]
-- Blazy
-- Server Scaling

- Cron automated tasks overview
- Updating Drupal 8
-- Update core via Composer
-- Updating Drupal 8 - overview of options
-- Update core manually
-- Update core via Drush
-- Update modules

Update and Migrate

- Migrating to Drupal

- Upgrading to Drupal 8
-- Upgrade using Drush
-- Preparing a site for upgrade to Drupal 8
-- Upgrade using web browser
-- Known issues when upgrading from Drupal 6 or 7 to Drupal 8
-- Upgrading from Drupal 6 or 7 to Drupal 8
-- Drupal 8 migrate modules
-- Contributing to Migrate
-- Learn key Drupal 8 concepts prior to upgrading
-- Customize migrations when upgrading to Drupal 8
-- Choosing the upgrade approach

- Converting Drupal 7 modules to Drupal 8
-- Step 3: Convert hook_menu() and forms
-- Step 2: Convert automated tests to Drupal 8
-- Debugging Drupal 8 module upgrades
-- Step 1: Convert mymodule.info to mymodule.info.yml
-- Intro & Before you start: Setting up a Drupal 8 module dev environment
-- Resources and tutorials
-- D7 to D8 upgrade tutorial: Convert hook_menu() and hook_menu_alter() to Drupal 8 APIs
-- D7 to D8 Upgrade: Generated HTML
-- D7 to D8 upgrade: fields, widgets and formatters
-- WSCCI Conversion Guide
-- WSCCI Conversion Guide - Best practices
-- WSCCI Conversion Guide - Pass 3
-- WSCCI Conversion Guide - Pass 2
-- WSCCI Conversion Guide - Pass 1
-- D7 to D8 tutorial: pathinfo module
-- D7 to D8 upgrade tutorial: Pants module
-- Step 5: How to upgrade D7 variables to D8's state system
-- Step 4: Convert Drupal 7 Variables to Drupal 8 Configuration

Mobile guide
- Responsive Images in Drupal 8
- Native mobile application development
- Mobile-specific website
- Web-based mobile apps
- Responsive web design
- Responsive Design + Server-side Components (RESS)
- Mobile testing tools
- Related mobile technologies
- Front-end performance

Multilingual guide
- Choosing and installing multilingual modules
- Translating configuration
- Translating content
- Install a language
- Enable language negotiation
- Menu translation in Drupal 8
- 'Clean URLs' in Drupal 8
- Fix Drupal 8 'Clean URLs' problems

External Libraries in Core
- External PHP Libraries
- External JavaScript Libraries
- External CSS Libraries

Multisite Drupal
- Multisite Drupal 8 considerations
- Multisite Drupal 8  Setup
- Multisite folder structure in Drupal 8
- Drupal 8 Multisite on a LAMP stack

Creating distributions
- How to Write a Drupal 8 Installation Profile

Accessibility
- Drupal 8 Accessibility Features
- Contributed Modules for Extending Accessibility in Drupal 8
- Hide content properly
- External Accessibility Resources

Thanks All. Wonderful inputs
@alexrayu - I suggest we can understand Information Architecture better if import the table of contents into Sitemap using a MindMap ?
I will start working on a MindMap for the above Information Architecture.

Looking at https://www.drupal.org/docs/8 after we got two levels of docs displayed, I think two-three guides stand out and don't really fit in:

• Cron automated tasks
• 'Clean URLs' in Drupal 8
• Multisite Drupal

These are quite specific technical guides that maybe could be moved some where?

Looks like this IA question is making good progress, I think next steps are to:
- Review the mindmap of the proposed solution to complete debate: Prabhu9484 -- any news on your mind-map idea :)?
- Manage edge cases: hansfn -- good catch. in what way do they not fit in? Maybe we can make a new subcat or you could suggest one?

Are we "done" with this draft if we accomplish those 2 goals?
I'd love to see us implement the change & close this out to begin measuring impact & how we can improve later...

Re #26. What if we move Cron automated tasks under Administering a D8 site? There's already at least some info about Cron there.

The Clean URLs guide probably doesn't need to be a guide, it's just one page. The one page is Fix Drupal 8 Clean URL problems and appears to be primarily trouble shooting information and docs on how to install and enable mod_rewrite. Which honestly are in my opinion out-of-scope for Drupal.org. I'm kind of inclined to review the page and roll any useful information into server requirements and then delete it.

The Drupal 8 Multisite guide had a handful of pages in it that were never published/approved. I went through and published most of them and deleted a few. There are 3 sub-pages now. I do still think it could move though. I'm kind of inclined to say information about multisite belongs under "Installing Drupal".

I also removed the guide that was previously at docs/8/migrating-to-drupal and redirected it to https://www.drupal.org/docs/8/api/migrate-api. The original had just a couple of sentences and no child pages.

The "Testing" and "PHPUnit ..." guides should probably be combined. Though I think this might be a bigger task than just me moving a couple things quick while I've got extra time. :P

Sure @svettes - thanks
So @svettes, please confirm that I will create a MindMap for
https://www.drupal.org/project/documentation/issues/2975147#comment-1268... ?

Thanks. My idea has been that the users are less technical, and hence we serve them first and in more detail, while we expect the developers to be able to better click through, so we can expect to have +1 / +2 levels of click-through with devs and the help still be usable to them..

@eojthebrave awesome comments, here are my thoughts on your proposals.
-Shan

• Cron: Yes, please. Like this solution, and it's easy. Imo cron is definitely a part of admin tasks.
• Clean URL's: Yes, please do a review & merge content as you see fit. I don't see a heading for 'server requirements', I think maybe you mean for this content to be merged into "web server" content heading under the "system requirements" topic? It makes sense to me to simply this, please proceed :).
• D8 Multisite: Actually. I might disagree w you here. The question of managing multiple sites is a bfd afaict, and I like it being in its own heading so readers can easily find out how to answer this question. I'm afraid that if we put it under installation, it might not be as findable. Does it hurt to leave it in its own heading for now? Anyone else have an opinion?
• Migrate: OK w/ me. Does this change the IA? I assume we want to keep it as-is but just change where the content directs as you suggest?
• Testing/Php Unit content merge: I don't see the PHP Unit guide you're talking about in the IA list from comment #24 now that you mention it. I assume you're proposing we merge these two guides into one content heading and having that live under the "testing" heading: Testing & PhP Unit. If that's right, please confirm & propose an appropriate page name, and I'll make an issue for it & follow-up.

^ If we agree on these next steps, I propose we review the "new" IA (will post it again w/ these changes outlined), and then implement the change.

@prabhu9484 - yes, please go ahead and make the mindmap :)
Thank you!!

Updated IA Proposal for review based on recent comments, please confirm :)

Changes:

• Moved "Cron automated tasks" under "Administering a D8 site"
• Removed "Clean URLs' in Drupal 8" and "Fix Drupal 8 'Clean URLs' problems" from the multilingual heading as we expect this content to become a part of "Web Server" under "system requirements" (Joe please confirm I have this right)

Understanding Drupal 8
- Overview
- Directory Structure
- Translation in Drupal 8
- Core modules and themes (Basic structure of Drupal 8)

USER HELP

System requirements
- Browser requirements
- Web Server
- Limitations of 32-bit PHP
- Database requirements
- PHP requirements
- Database server

Installing Drupal 8
- Before a Drupal 8  installation
- Step 1: Get the Code
- Step 2: Install dependencies with composer
- Step 3:  Create a database
- Step 4: Configure your installation
- Step 5: Run the installer
- Step 6:  Status check
- Trusted Host settings
- Quick-start: launch a local demo version of Drupal 8 using 4 brief steps

Administering a Drupal 8 site
- Automated Cron
- Cron automated tasks overview
- Internal Page Cache
- Getting started with Drupal 8 administration
- Managing content
- Working with content types and fields
- Working with content types and fields

Extending Drupal 8
- Installing modules' Composer dependencies
- Installing Drupal 8 Modules
- Overview
- Installing Themes
- Interface guidelines (Seven admin theme)
- Finding Contributed Modules
- Uninstalling Modules
- Installing Modules from the Command Line
- Updating Modules
- Module Documentation and Help
- Troubleshooting
- Module Configuration
- Installing Sandbox Modules

Contributed modules (This is list of modules? Misleading?)
- Default Content
- Varbase Editor
- Business Rules
- Youtube Gallery
- Permissions by Term
- Block Style Plugins
- Developer Suite
- Commerce Braintree
- Feature Toggle - Deprecated
- Socialfeed
- HelloSign
- [marked for deletion]
- Marketing Cloud

Contributed themes
- Drupal8 W3CSS Theme Configuration

Distributions
- deGov
- Thunder
- Install deGov 1.x
- Install deGov 2.x
- Upgrading from deGov 1.x to 2.x

DEVELOPER HELP

Drupal 8 APIs
- Runtime Assertions
- Installation & Setup Guide
- Configuration

Theming Drupal 8 (Collapse or move extended list to a subpage)
- Defining a theme with an .info.yml file
- Drupal 8 Theme folder structure
- Adding Regions to a Theme
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
- Classy themes css selectors
- Including Default Image Styles With Your Theme
- Working with breakpoints in Drupal 8
- Including Part Template
- Preprocessing and modifying attributes in a .theme file
- Using attributes in templates
- Sub-theming: Using Classy as a base theme
- Creating a Drupal 8 sub-theme, or sub-theme of sub-theme
- Creating advanced theme settings
- Theming differences between Drupal 6, 7 & 8
- Drupal Twig conversion instructions (tpl.php to html.twig)
- Upgrading classes on 7.x themes to 8.x
- Sub-Theme inheritance
- Creating automation tools for custom themes (Gulpjs)
- How to edit ALT tag on your site logo
- Theming Overview: How data is displayed
- Z-indexes in Drupal 8
- Using CSS pre-processors
- Add Google Webmasters Tools verification meta tag via the .theme file

Creating custom modules (Collapse or move extended list to a subpage)
- Building a Views display style plugin for Drupal 8
- Creating a custom Field
- Create a custom field widget
- Create a custom field formatter
- Create a custom field type
- A practical guide to building basic Drupal 8 modules
- Testing
- Defining a Block
- Settings
- Theming
- Basic structure
- Prepare a Module skeleton
- Add a composer.json file
- Naming and placing your Drupal 8 module
- Let Drupal 8 know about your module with an .info.yml file
- Adding Custom Blocks to your custom Module
- Add a Default Configuration
- Use Config in Block Display
- Process the Block Config Form
- Add a Form to the Block Configuration
- Create a custom block
- A "Hello World" Custom Page Module
- Going further
- Add a menu link
- Add a routing file
- Adding a basic controller
- Create a custom page
- Getting Started - Background & Prerequisites (Drupal 8)
- Defining and using your own configuration in Drupal 8
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module
- Understanding Hooks
- Add module to drupal.org
- Event Systems Overview & How To Subscribe To and Dispatch Events

Configuration management
- Changing the storage location of the sync directory
- Workflow using Drush
- File system based workflow
- Workflow using the Drupal UI
- Managing your site's configuration
- Keeping Your Local and Remote Sites Synchronized - Drupal 8

Testing
- Converting D7 SimpleTests to Drupal 8
- Simpletest Class, File, and Namespace structure
- Types of tests in Drupal 8
- Javascript testing using Nightwatch

Understanding Drupal version numbers
- Which version of Drupal core should I install?
- Which version of contributed modules, themes, and translations should I install?
- When is the next release?
- Which version of Drupal am I running?
- Which version of a module or theme am I running?
- What about upgrading and backwards compatibility?
- Drupal release versions
- Development snapshots
- What do version numbers mean on contributed modules and themes?
- What are alpha and beta releases, and release candidates?
- Release stable version
- Drupal release history

Sequrity and Maintenance

- Security in Drupal 8
-- Writing secure code for Drupal 8
-- Security of generated PHP files
-- Secure configuration for site builders
-- Secure Database Queries
-- Drupal 8: Sanitizing Output
-- US NIST Password Guidelines review

- Performance and Scalability
-- Content Delivery Network [CDN]
-- Blazy
-- Server Scaling

- Updating Drupal 8
-- Update core via Composer
-- Updating Drupal 8 - overview of options
-- Update core manually
-- Update core via Drush
-- Update modules

Update and Migrate

- Migrating to Drupal

- Upgrading to Drupal 8
-- Upgrade using Drush
-- Preparing a site for upgrade to Drupal 8
-- Upgrade using web browser
-- Known issues when upgrading from Drupal 6 or 7 to Drupal 8
-- Upgrading from Drupal 6 or 7 to Drupal 8
-- Drupal 8 migrate modules
-- Contributing to Migrate
-- Learn key Drupal 8 concepts prior to upgrading
-- Customize migrations when upgrading to Drupal 8
-- Choosing the upgrade approach

- Converting Drupal 7 modules to Drupal 8
-- Step 3: Convert hook_menu() and forms
-- Step 2: Convert automated tests to Drupal 8
-- Debugging Drupal 8 module upgrades
-- Step 1: Convert mymodule.info to mymodule.info.yml
-- Intro & Before you start: Setting up a Drupal 8 module dev environment
-- Resources and tutorials
-- D7 to D8 upgrade tutorial: Convert hook_menu() and hook_menu_alter() to Drupal 8 APIs
-- D7 to D8 Upgrade: Generated HTML
-- D7 to D8 upgrade: fields, widgets and formatters
-- WSCCI Conversion Guide
-- WSCCI Conversion Guide - Best practices
-- WSCCI Conversion Guide - Pass 3
-- WSCCI Conversion Guide - Pass 2
-- WSCCI Conversion Guide - Pass 1
-- D7 to D8 tutorial: pathinfo module
-- D7 to D8 upgrade tutorial: Pants module
-- Step 5: How to upgrade D7 variables to D8's state system
-- Step 4: Convert Drupal 7 Variables to Drupal 8 Configuration

Mobile guide
- Responsive Images in Drupal 8
- Native mobile application development
- Mobile-specific website
- Web-based mobile apps
- Responsive web design
- Responsive Design + Server-side Components (RESS)
- Mobile testing tools
- Related mobile technologies
- Front-end performance

Multilingual guide
- Choosing and installing multilingual modules
- Translating configuration
- Translating content
- Install a language
- Enable language negotiation
- Menu translation in Drupal 8

External Libraries in Core
- External PHP Libraries
- External JavaScript Libraries
- External CSS Libraries

Multisite Drupal
- Multisite Drupal 8 considerations
- Multisite Drupal 8  Setup
- Multisite folder structure in Drupal 8
- Drupal 8 Multisite on a LAMP stack

Creating distributions
- How to Write a Drupal 8 Installation Profile

Accessibility
- Drupal 8 Accessibility Features
- Contributed Modules for Extending Accessibility in Drupal 8
- Hide content properly
- External Accessibility Resources

Looks good to me. Happy to see the Cron and Clean URL guides gone. Don't have any great suggestion about where to move the Multi-site guide so I'm fine with keeping it.

PS! The list of 2nd level guides is becoming outdated. For example Distributions where I have cleaned up deGov. Maybe just update comment 35 to make it clear that it isn't an up-to-date list?

@svettes my comments about the Testing and PHP Unit guides was based off of looking at the existing content of https://www.drupal.org/docs/8. In the outline in #35 I think that we need to add the PHP Unit guide underneath the "Testing" section.

I think the list in #35 is looking good.

In addition to producing this list, I think we should also be trying to generate some documentation that helps explain how/why things are organized the way they are. And basic guidelines someone can follow in order to properly slot their new content into this new IA. Otherwise we risk just ending up right back where are now with content just being placed sort of "Meh, wherever it seems to fit."

Thanks all
@svettes - based on list #35, please find attached the MindMap image of the list.
Read the Right Hand Side then Left Hand Side.
Unclear headings are marked in bold.

Please review

The mindmap was helpful. I see one problem - "Updating Drupal 8". It's as much a user task as "Installing Drupal 8". Maybe move it out of the "Sequrity and Maintenance" section as that is developer focused?

PS! If the Mindmap is developed in an open source/free tool, it might be useful to have the source of the mindmap attached to this issue too.

Thanks for the kind words @hansfn.
I have created the MindMap in FreeMind. I tried to upload the .mm file, but is not in the allowed extension list of the file uploader.
Please advise ?

Just zip the file and upload with .zip extension.

Thanks @hansfn - here it is

Hello guys - any updates on the MindMap Information Architecture ?

The first link in the Problem/Motivation section goes to the d.o homepage, so I don't know which pages this issue is about. Can someone fix that?

done.

The structure of the documentation has changed since this was created. I am not sure how much of this feed in to that process. I was involved in that process some years ago and I did not know about this issue. I worked with others in Slack.

So, I think this is now outdated. Someone correct that if I am mistaken.