Background

Currently the landing page for the new documentation system https://www.drupal.org/docs/ does not exist. It simply redirects to https://www.drupal.org/docs/8. While the old /documentation page is in the 'in progress' state, linking to some of the new documentation guides, as well as, some of the old book pages. Once the migration is done (or very close to done), we need to create a new landing page to reflect the new documentation system (per-version split, new IA, maintainers, etc.), and the new D8 user guide.

With the new system, we have 4 top level landing pages for different types of documentation:

Those will need to be redesigned as well. Right now they use default 'documentation guide' layout, where they simply list all of their child content. As we add more and more content, this won't be practical.

Questions:

  • Do we actually need an 'umbrella' landing page on top of the 4 listed above? If yes, what is its goal and audience?
  • As an alternative, we could make sure each of those 4 pages is well-designed, and default /docs to docs/8 with an easy way to switch to the other 2.

Work in progress

We did have a few early mockups, which I'll find and add. Those were based on the assumption that we do not need a separate top level page. That instead we default to displaying D8 content first (basically docs/8) and provide an easy way to switch to D7 or Developer docs.

Implementation details

Todos:

  • Answer the questions above

  • Create a wireframe of page layout/content
  • Update wireframe #49 with search box use case in the UI
  • Design the page
  • Implement the new landing page at /docs
  • Delete /documentation and redirect to /docs
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

tvn created an issue. See original summary.

eojthebrave’s picture

Issue summary: View changes

Adding user guide to the list of landing pages.

banoodle’s picture

I tested all the anchor links on this page today and everything is working now.

banoodle’s picture

Status: Active » Fixed
banoodle’s picture

So Sorry! I meant to update other issue.

banoodle’s picture

Status: Fixed » Active
eojthebrave’s picture

I think we might still need this landing page. And that there are likely more than just 4 things to link to. Right now the landing page at https://www.drupal.org/documentation in addition to the 4 main guides above links to:

- api.drupal.org
- Git documentation
- Callout + link to documentation about contributing to the documentation

I don't really foresee those fitting into any of the existing guides, so do they sort of become guides of their own?

jjpoole’s picture

[moved from dup issue]
Simplify and streamline this page into 3 primary sections: Drupal 8, Drupal 7 and Developers. Each of these primary sections to have a set of standard root categories that all current and future documentation can be housed in. This layout should be simple and welcoming, easy to scan and provide entry points to categories.

doc home

I like the idea of being able to promote an item (like User Guide), creates a nice, welcoming entry point for newer users.

We could use the top gray bar to welcome people to learn about contributing to the docs (linking to related content). I assume the vast majority of people visiting the docs are looking for help (via documentation), probably not because they want to contribute.

The current Doc homepage has a lot of text to read (as well as tabbed navigation, that is only seen on this page), there isn't much priority or weighting on anything specific to help guide one into the content the might need. With this layout we can make it very easy to first identify you main category (D8, D7, Developers) and then scan simple, basic categories to get them headed in the right direction.

eojthebrave’s picture

We could use the top gray bar to welcome people to learn about contributing to the docs (linking to related content). I assume the vast majority of people visiting the docs are looking for help (via documentation), probably not because they want to contribute.

That makes sense to me. Use the space to explain, that these docs are created and maintained by the community, and you can help. And then link to more information on helping.

Could you mock up an example that includes the User Guide as an entry point for new users.

What are the next steps here? Figuring out what the content of each of those blocks should be and the order to list things in maybe? Are the existing lists your recommendation, or were they just compiled to show an example of what it might look like?

jjpoole’s picture

FileSize
546.92 KB

Here's a revision with some simple treatment to highlight the User Guide, this could be used (but not required) for the other 2 categories.

I didn't put too much thought into the first level of categories, so these are just some examples but I'm guessing many of these would work. We don't want an overwhelming number of categories (maybe we shoot for 12 as show here?), nor do we want things overlapping and having users wondering where they might find something. I don't think these should be version specific either, categories for D8 should be the same for D7 (and D9!)... maybe there are some exceptions... not sure. Developers categories will be different obviously.

Doc Main 1.1

jhodgdon’s picture

I like it!

One concern I have is that the developer docs... Some of them are under
https://www.drupal.org/docs/develop

And some of them are under the D8 and D7 sections, such as this section that is currently living under D8:
https://www.drupal.org/docs/8/phpunit/phpunit-javascript-testing-tutorial

That probably needs to be fixed. I think the docs under docs/develop are version-independent perhaps, and the ones under either d8 or d7 are version-specific? But even if that is the case, it's confusing, and separating the main page into D8, D7, and Develop will just add to that confusion.

Wim Leers’s picture

Agreed with jhodgdon that portraying the "Developers" section as version-independent is confusing. Many/most things are version-dependent.

jhodgdon’s picture

Possibly another way to handle it would be to have a Developers section on the landing page, with 3 links:
- D7 developer information
- D8 developer information
- version-independent developer information

But I'm not sure ... one thing that is also confusing is the term "developer" anyway. People use it for a lot of things, independent of the Drupal community. For example, "web developer" is often used to mean 'someone who develops [creates] web sites'. But in the context of drupal docs, "developer" means "php programmer", which is a way narrower definition than in society at large...

eojthebrave’s picture

What if we come up with a different heading for the 3rd section? Something other than "Developer". Which I agree could be a bit confusing in this context. Though, I don't know what that heading should be.

The content that is in that section currently is (or at least should all be) version independent. Things like using Git, setting up a localhost, or coding standards. https://www.drupal.org/docs/develop. During the migration to the new docs guides/pages we tried really hard to make sure that this stuff was version agnostic, and that anything version specific is under either docs/8 or docs/7. We're trying to get away from having the situation where a single page would documentation both the D8, and D7 way of implementing a form for example.

On the current /documentation page it's listed as, "Developer documentation: Documentation for developers about tools, processes, and standards that is not specific to a major version of Drupal."

Any thoughts about what a better heading might be for this section? In the future we could also add additional non-version specific content here as well. And even content that isn't for "developers".

jhodgdon’s picture

maybe:

Tools, Processes, and Standards for Developers

It might be a bit wordy, but it would be specific

Probably just Tools & Standards would be enough?

eojthebrave’s picture

I like "Tools & Standards". That seems like it captures that content that is there currently.

jhodgdon’s picture

Yeah, I think so too, so the screenshot in #10 would have headings:

Drupal 8

Drupal 7

Tools & Standards

That seems pretty clear to me.

eojthebrave’s picture

Adding related issue #2827861: Promote new Drupal 8 User Guide. Fixing this one will at least partially address, if not resolve, that one as well.

jhodgdon’s picture

One other random thought that I've been meaning to add to this issue for a while:

For developers (in the sense of PHP programmers, there are many other meanings of the word "developer") using Drupal 8, we spent a bunch of time in the D8 development cycle making sure that people who ended up at api.drupal.org would have a brief intro to all the aspects of programming with Drupal 8, and links to more detailed information that exists on drupal.org. So I really think that we should highlight that link on the Documentation page -- that is the best organized and most concise place for module developers or would-be module developers to start at to find documentation.

eojthebrave’s picture

Just to be clear, you think we should highlight a link to api.drupal.org? Seems reasonable to me.

jhodgdon’s picture

Yes, I think that under the Drupal 8 heading, there should be a link to api.drupal.org. I'm not sure about the link title... I guess it depends on whether there are just links or if there is also explanatory text like we have now on /documentation... But somehow, (in my opinion) we need to get across the point that api.drupal.org is the entry point for developers of custom modules, PHP programmers, people who want to contribute to Drupal 8 development (core or contrib modules), and the like. In addition, it is the Drupal API documentation.

For Drupal 7, the api.drupal.org landing page is not as good... We should probably put a link to https://api.drupal.org/api/drupal/7.x in the D7 section, but I would just say it is a link to the Drupal API documentation. The better entry point for D7 development is ... let's see where is it now... Hm, I guess we have https://www.drupal.org/docs/7/creating-custom-modules and https://www.drupal.org/docs/7/api .

We should also I think have links in both D7 and D8 sections to the Theming Guides for each version, as Themers are also an important audience.

hansfn’s picture

Not sure how this is moving on, but my concern isn't the landing page - https://www.drupal.org/documentation - but the start page for each version: https://www.drupal.org/docs/7 and https://www.drupal.org/docs/8

Those two pages are really, really problematic because the list is so long and there is no apparent grouping or ordering. I have tried a few times to move important stuff up on the list, but that doesn't really help. I think we need another level of guides - or "sub start pages".

I think this is urgent and should be too hard to get done. If some one can explain what the options for organizing are, I can come up with a proposal for organization.

eojthebrave’s picture

Yeah, that does seem like a good thing to address. Though I think it probably warrants it's own issue. As this one is still important too I think. I do think whatever we decide to do with the 7/8 landing pages will help inform what's done here though.

As for organizing. As far as I know, the only thing that's currently available would be to create sub-guides, and group things together into those sub-guides. It's pretty easy to move things from one guide to another so that shouldn't be a problem. I'm happy to help with that. As well as to review/help with coming up with a strategy for categorizing things.

Alternatively, if you've got ideas about how things to could be better grouped/organized on these pages we can also propose them and see what can be done on Drupal.org to accommodate.

grasmash’s picture

FileSize
320.83 KB

Revisiting this issue after the recent Documentation Initiative.

I'd like to propose a revision to the wireframe that incorporates a few new concept:

  • Official Docs vs Community Docs designation.
  • A dedicated "getting started" guide
  • Version control indications (making the display of both D7 and D8 on the same page unnecessary).

I love the grouping that the original wireframe introduced, and I tried to incorporate that under the "Drupal 8" and "Developer Docs" subheadings.

Wireframes

Here is a related mockup of what the "Getting Started" section would look like when you click into it. Notice the table of contents linking to anchors for same-page headings.

grasmash’s picture

FileSize
303.92 KB
grasmash’s picture

jhodgdon’s picture

Those look pretty interesting! A few comments/notes/questions:

a) I don't think we will currently want to have more than one version on drupal.org, until 9.x comes out. We don't support more than one 8.x version at a time.

b) A new official Getting Started Guide sounds good, but is that a new initiative to create it? How is it different from #2956879: Proposal: Create and promote new "Quick-start guide" pages and from the User Guide?

Hm... Maybe I'm confused and #2956879: Proposal: Create and promote new "Quick-start guide" pages is what you're calling the official getting started guide? Very confused about this. I just don't know what the Getting Started Guide here is supposed to be?

grasmash’s picture

Getting Started == Quick Start. Sorry about the confusion.

> We don't support more than one 8.x version at a time.

I think that may be changing in the near future. We way begin to support the penultimate minor release, in which case it would be good to show the related documentation.

grasmash’s picture

@jhodgdon As I think more about how to build this documentation out in the repo, it makes sense to have a Drupal "docs" repo that would contain all of the version controlled, ASCII docs-parsed documentation including the user guide. An ideal repo structure would look something like:

- assets
- scripts
    - auto_screenshots
- source
    - guidelines
    - guides
        - composer
        - config_management
        - getting_started (quick start)
        - user_guide
            - en
            - fr
            - etc
    - landing_page.txt
- templates

It seems like the work of configuring feeds on Drupal.org would be simplified if there was one repo, rather than having a repo per guide. It would also be ideal to share templates, guidelines, and scripts with the user guide wherever possible. I'd like to avoid re-work and duplication.

Obviously this would require modifications to the user guide's structure and feed importers. I completely understand if you're not open to that. I think the alternative is to have a docs repo for everything except the user guide, and let the user guide be an exception to the rule. It's less intuitive for readers and contributors, but I understand that there may be other considerations.

Also, I'll admit that at least in the short term, I'm disinclined to support multiple languages and publish ebooks for all of the guides. It seems like it increases the scope a good deal, and I worry that it would cause us to lose momentum and also have a higher maintenance burden later. That may be a strong reason to keep them separated.

Let me know your thoughts.

grasmash’s picture

FileSize
318.97 KB

Updating "Getting Started" wireframe.

  1. Added anchor hash tag, and discussed in https://www.drupal.org/project/documentation/issues/2943370#comment-1260...
  2. Added detail (dev/maintained/unmaintained) to versions dropdown.
  3. Added "was this helpful?" feedback mechanism.

grasmash’s picture

FileSize
317.74 KB

Fixing typo in image.

jhodgdon’s picture

RE #29, please bring this up on the other issue about the quick start guides. But probably not, I already suggested it there and people said no. I think the problem is that the maintainers/governance/contributors for these quick start guides is probably not the same as for the User Guides.

The feeds config doesn't really care about one repo vs. several... it's probably better to have project/repo structure that corresponds to project governance/maintainers, rather than trying to second guess what would be easier on drupal.org.

jhodgdon’s picture

OK, I don't get it now... So Getting Started is the same as the quick start guides... What text is on the Getting Started page exactly? Do we need a whole page to introduce what is currently only 3 guides?

grasmash’s picture

FileSize
324.83 KB
327.85 KB

What text is on the Getting Started page exactly? Do we need a whole page to introduce what is currently only 3 guides?

Good point. That was confusing. I've updated the wireframes to simply have a "Docs Overview" label for the page in the menu and breadcrumb. It's intended to be the documentation landing page that is currently at /documentation. "Getting Started" is just a heading at the top of the page with a brief blurb that will steer beginners toward the Quick Start Guide as a starting point.


jhodgdon’s picture

Some comments about the latest design:

a) Drupal 7 documentation still needs to be included in the landing page. It seems to be missing from the latest proposals?

b) I don't think we need a whole section for API Docs. I think it would probably be better, as was suggested in previous ideas in this issue, to put that into the developer docs section.

c) We also need some text in some of these sections. Developers, for instance, need to know that if they're doing D8 development, some of their docs are under D8 and some under Developer, because the developer section is for version-independent information. That was clearer in some of the previous ideas for the design.

d) See also comments #13-17 on these subjects.

jhodgdon’s picture

I forgot to say THANK YOU for restarting this discussion @grashmash!

So, I think my suggestion from #35 would be to incorporate the conclusions in #17 and #21, along with some good ideas that are in #34.

So the outline of the /documentation landing page could be:

  • Getting Started
  • Official Guides
  • Community and API Documentation
    • Drupal 8
      This section would include a few key links (developer docs, API docs, installation, and a few administrator links maybe?), but mainly link to the D8 docs landing page, which would have all the D8 links
    • Drupal 7
      Similar to the D8 section
    • Developer Tools & Standards
      I think this section might need a little introductory text to explain that it's for version-independent information for developers, and then it would have links for coding standards, Git, managing projects on drupal.org, etc. See screenshot in #8 for ideas, but probably it could link to a Developer Tools and Standards landing page, plus have a few key links, much like the D8 and D7 sections would be listing a few links but mainly linking to the D8 and D7 landing pages.

Thoughts?

grasmash’s picture

a) Drupal 7 documentation still needs to be included in the landing page. It seems to be missing from the latest proposals

The version dropdown in the upper right is intended to address this. The entire landing page would be populated via an 8.x branch. If users want 7.x docs, then would select 7.x from the drop down. One goal of this design is to remove the need to list and represent all D8 and D7 docs on the same page.

I don't think we need a whole section for API Docs. I think it would probably be better, as was suggested in previous ideas in this issue, to put that into the developer docs section.

I'm not convinced of this. Combining "Community Docs" and "API Docs" under one heading doesn't make sense to me. The subject matter for the two categories of documentation are very different, the format is different, and they are created and maintained differently. There is also a fairly well established precedent for separating API docs from other documentation in other frameworks, e.g., Symfony and Laravel.

We also need some text in some of these sections. Developers, for instance, need to know that if they're doing D8 development, some of their docs are under D8 and some under Developer, because the developer section is for version-independent information.

Agreed. I've added short blurb under each heading, but they need to be fleshed out more to describe the scope and purpose of each documentation type. I'd like to iterate on that once we've established that the general layout and groupings are satisfactory.

jhodgdon’s picture

Maybe we should postpone this on #2975147: Refactor Information Architecture of Documentation section? It seems like figuring out a reasonable IA would be a good first step to this issue, since it would help define what links need to be on this page...

eojthebrave’s picture

I think it would be great if we could come up with a version of this that we can agree on as good enough for a first iteration. We've got some tools in place on Drupal.org now that will allow us to use Panels to create a landing page for /documentation, and it would be great to make use of that as an interim solution to eventually having this possibly be managed by version control.

For the D7 vs D8, we could do something like either have both one one page for now. Or, do something like /documentation, and /documentation/7 and have a link to toggle between the two. Until we can implement a drop down, and more granular (8.5.x, 8.6.x, 7.x) in the future.

And finally, while I'm a big fan of doing the work to figure out a better IA for documentation, I would hate to see this stall for a long time while we do that. I believe we can come up with something here that's good enough to be better than the existing landing page. And that can continue to evolve as our understanding of what it should contain changes.

Adam Neutrik’s picture

Wow, a lot of great work in here. Thanks to all! And what a great looking mock-up at #10!

grasmash’s picture

I think it would be great if we could come up with a version of this that we can agree on as good enough for a first iteration. We've got some tools in place on Drupal.org now that will allow us to use Panels to create a landing page for /documentation, and it would be great to make use of that as an interim solution to eventually having this possibly be managed by version control.

Agree, I'd like to push forward and make tangible progress to the degree that we can.

wturrell’s picture

Who actually looks after /documentation now? (or who has the ability to edit it)?

The HTML source suggests it's mostly a single block, rather than a generated view? In which case, I think if you gave someone(s) a few hours to iteratively improve it they could restructure the headings, make the explanations more helpful/specific, better promote the User Guide, link off to other useful place such as the YouTube channel and so on…

The discussions out of that might help form a basis for some of the actual text and links on the new version, once the wireframe is agreed.

grasmash’s picture

Who actually looks after /documentation now? (or who has the ability to edit it)?

I just got access to edit it in the last few weeks. It is now a panelized node, which offers some more flexibility than it formerly had.

The designs that I posted would require a few Drupal.org customizations:

I'd still like to set our sights on something like #34, but in the mean time, I think we need to agree on an interim landing pages that uses the currently available tools. I believe we could create something like this:


Note that I've split these into a Drupal 8 (default) and Drupal 7 landing page.

eojthebrave’s picture

I also have permissions to edit /documentation.

+1 to the proposal in #43 as a way to move forward. I believe the only thing that might still be controversial is the content of the "Community Docs" section. But again, I think anything is an improvement over the existing page. :) And, I think once the IA Refactor issue complete we'll have a better understanding of what should go there.

svettes’s picture

While I prefer the option in #34, I will take #43 because it gets us closer to our goal of consolidating info in a landing page which organizes content by version and type of doc.

I like the proposal of "official" v "community maintained" because it doesn't stop people from creating content, but also distinguishes amateur docs from ones that are verified. As a docs consumer, I like being able to know that the docs I'm consuming are accurate and have been reviewed before publishing. As a contributor to docs, I like being free to add my content if I deem it useful w/o a lengthy review process.

^ It suits both audiences from my PoV.

+1 to 43, I think we should move forward and iterate on this as it's an improvement on what we have today.

hansfn’s picture

Just two quick comments:

  1. We have to stop saying things like "distinguishes amateur docs from ones that are verified". We have to remember that a lot of the current community docs are written by experts - module maintainers, (core) developers and long-time Drupal doc writers. At the same time there is outdated, confusing, badly written and organized docs. (No need to discuss this - this is just a reminder.)
  2. Joe raises an important issue - the content of the "Community Docs" section. Right now the mockup has 6 rather random items/categories. Is the planned item/categories listed/discussed some where? How many - limit to 12 as suggested in comment 10?
alexrayu’s picture

FileSize
81.61 KB

There will be 2 types of users who will be looking at the docs - those who need to learn the basics and concepts, and how to use Drupal, and the coders who need a reference.

As a first time user, when I see this setup, with my questions like what are the basic things about Drupal - download, install, architecture overview, common likeness/difference to other cms, main patterns in ui/architecture, how to i create content, aliases, etc? As a learning developer, I have needs to know how I can do theming, write modules, and access lists of functions, hooks, and classes. When I look at current docs, it's a nomenclature, built in a way to help manage it, but not in a way to help me find what I want. Librarian-based, rather than reader-based. This approach makes it very hard to use for me, making stackoverlow and blog posts almost always preferable to our standard docs. In some cases, renaming the links and rethinking the main docs structure can suffice to address some of that.

On the layout/flow side, need to have clear headings with links underneath. Currently at DO we have some sections with linked titles, some with unlinked titles and links underneath it. (See attached image) - which adds additional messiness.

On the logical side, as a Docs user, I don't really care for the "official" vs "unofficial" main headings, I care for the logical arrangement of where I can find things. Basic guide vs user guide vs dev guide, something like that.

Layout wise, I like in #34 that left panel that can serve as a strong point of reference. I am getting lost in the tangles of the docs all the time. A point of reference would be handy (though not sure if it's easily doable given the structures we now have). Panel aside, #43 seems to be a better organized version of what we have now, though most of the above user orientation idea applies to it as well.

xinyuma’s picture

Great discussions everyone. I want to add my comment on the design & layout side of this story:

For me landing pages should give users a simple and clear overview of a certain topic, and importantly nothing else.

I think #10 is the best because:

  • It has a simple layout. Similar blocks are placed on top of each other. Users don't need to spend much effort to understand the meaning of different regions on the page, like in #34 and #43
  • It has limited amount of components. The same block is re-used to show drupal 7, drupal 8 etc. It is so much easier for users to learn what is in each block
  • It gives quick access to newest/popular deeper pages of each category. This could be convenient too

#34 or #43 is good for pages deeper in the structure since the side-bar menu allows quick access to different part of the documentation.

grasmash’s picture

FileSize
699.79 KB

I'd like to focus on the next step, which is getting an interim landing page in place using only existing tools. #43 is built using existing tools, the rest require changes to Drupal.org.

Joe raises an important issue - the content of the "Community Docs" section. Right now the mockup has 6 rather random items/categories. Is the planned item/categories listed/discussed some where? How many - limit to 12 as suggested in comment 10?

The mockup was intended to represent the layout rather than than full content. I've done a more thorough "preview" here:

https://docinitiative-drupal.dev.devdrupal.org/documentation

Rather than making IA decisions, I've just exactly represented the existing IA. I don't think it's a good one, be we should reserve discussions for refactoring the IA for #2975147: Refactor Information Architecture of Documentation section.

Notes about the limitations:

  • Doc trees are manually curated
  • Menu links cannot be nested
  • CSS has to be injected at the page level
  • Book ads cannot be removed

jhodgdon’s picture

Thanks! It's great to have something concrete to look at, rather than talking about abstracts.

So, looking at https://docinitiative-drupal.dev.devdrupal.org/documentation I have some thoughts/comments:

I personally think that the landing page has way too much on it. For example, I don't think we should list the chapters in the User Guide, or any of the topics within the Drupal 8 API pages on drupal.org, or pages on api.drupal.org. Rather, for those items, I think we should just link to the top-level page or site, and give a brief description of what people would find there.

I also think it might make sense to do that for the two sections under the Community Guide. I think it would be way more helpful for people landing at /documentation to see a brief description of what is under Develop vs. Drupal 8 (the distinction is probably far from obvious -- under Develop we would find documentation about coding standards and other docs for developers that are more or less version-independent, and the main Drupal 8 community docs page is for things that are version-dependent).

The other question is how to group things. I think that the API docs and Develop belong together, as far as audience is concerned. Also, technically the API documentation that is on drupal.org is part of the community docs, so to me, putting it with the "API" section is not all that accurate from a "where does it come from" perspective... But in any case, I don't think the "where does it come from" perspective is all that useful for the audience, is it?

grasmash’s picture

Also, technically the API documentation that is on drupal.org is part of the community docs, so to me, putting it with the "API" section is not all that accurate from a "where does it come from" perspective...

I agree, this doesn't feel quite right to me. I'll try your suggestion.

I personally think that the landing page has way too much on it. For example, I don't think we should list the chapters in the User Guide, or any of the topics within the Drupal 8 API pages on drupal.org, or pages on api.drupal.org.

I disagree. I've had tremendous difficultly discovering exactly what is in each of the sections, and I found it very frustrating to click into each guide to determine its contents. I personally find it very valuable to get an overview of the "chapters." It reduces browse time significantly. The other benefit is that it makes the IA very obvious. In this case, it makes it clear very clear that the IA for the community guide is in bad shape.

jhodgdon’s picture

The problem is that we would be maintaining the lists of contents in more than one place, which means that the landing page would get out of date, most likely. And making it so that whenever a new guide is added we have to go to several places to make sure it is visible is a recipe for non-maintainable pages.

grasmash’s picture

The problem is that we would be maintaining the lists of contents in more than one place, which means that the landing page would get out of date, most likely.

Good point, I agree. I've refactored the implementation so that the chapters are dynamically displayed from by using an OG Menu block, so that shouldn't me an issue now.

And making it so that whenever a new guide is added we have to go to several places to make sure it is visible is a recipe for non-maintainable pages.

Is there another place where the guides are listed?

Thanks your your input, it's great having another person thinking about this.

jhodgdon’s picture

Each Guide is listed on its parent Guide page.

So, for example, all the topics in a single user guide chapter are listed on the chapter page, and the chapters are listed on the user guide landing page.

I believe that all the Drupal 8 guides are automatically listed on
https://www.drupal.org/docs/8/
(similar page exists for D7), and all the developer guides are listed on
https://www.drupal.org/docs/develop
right? Isn't that where you got the lists from? And the API guide for Drupal 8 is a subpage of docs/8.

So I don't think we should try to duplicate the lists on those two pages on the main docs landing page. I think it would be more useful to (a) point people towards the right starting point and (b) as is being discussed (kind of) on the "redo architecture" issue, think about how to better organize both of those pages.

grasmash’s picture

So I don't think we should try to duplicate the lists on those two pages on the main docs landing page.

I agree, but I'd prefer to solve that problem by making pages like the Drupal 8 Community Guide landing page more useful. A huge list of gray blocks doesn't provide a good means of browsing the contents, especially considering that you need to click into each guide before seeing what chapters it contains. I really think that listing the guides and their chapters on the main documentation page is the best user experience.

That leaves the question, "what's the right UX for the guide landing pages?" I'm going to spend some time prototyping.

alexrayu’s picture

FileSize
110.29 KB

#49 is actually something I could use. I have found what illustrates my point at wp-codex (see image attached). I am not suggesting to just copy things over, but there are some wise ideas there:

1. Advanced API reference is behind a link, but it's an early link.
2. Clearly indicated basic ideas section, where I can learn, what is this CMS and main concepts.
3. A section for the users. How do I use the CMS.
4. A section for the devs. How do I develop. With themes and modules as sub-categories.
5. Contribute.

Above sections are structured so as the users will find what they want.

One big thing about #49 is the headings for "Official Guide" vs "Unofficial Guide" - don't help user at all. In fact, the official guide could be a single link - something like "An official introduction to Durpal".

If we are looking for a good logical arrangement, we could see how the WP arranged it and reuse the logic where we can.

eojthebrave’s picture

I like that the proposed landing page has a larger and more comprehensive list. Especially if the problem of keeping those lists up-to-date wherever they occur can be solved technically instead of manually. I personally much prefer to browse a really big list than to have to click into many sections and back out when they don't contain what I'm looking for. We could try and write some text that gives you a sense of what each section contains so you can try and decide if that's the one you want. Or we can just show you what's in it, and save you a click (or likely many clicks).

webchick’s picture

Yeah, huge +1 to providing an overview immediately on the landing page. It saves peoples clicks, as well as exposes the full extent of the content underneath which will help us to much better organize the underlying IA (I had NO idea there were this many things underneath the Drupal 8 docs for example: https://docinitiative-drupal.dev.devdrupal.org/docs/8)

The only other thing we could maybe play with a bit here is only showing that extended "table of contents" on the main landing page for the curated docs (User Guide + API reference atm), to act as further encouragement to click here first, and only click there if you don't see what you're looking for.

jonathanshaw’s picture

I understand there are limitations to what can be achieved quickly with current tools, so maybe this needs to be a follow-up:
what about Search?

#49 has dropped search from the landing page. But for many people it's their preferred way of obtaining information.

I'm struck by the docs page for Xero (a UI-obsessed complex web app for book-keeping) at https://central.xero.com/s/. You'll see that they have actually massively de-emphasised taxonomy in favour of search, very likely because their user testing found that this gave the best experience.

One point: search should be version-specific. Searching for configuration from a D8 page and turning up D7 documentation would be very confusing and frustrating.

grasmash’s picture

Great point. Dropping the search bar was not intentional. We will not do that when it is merged.

However, I had not considered splitting the search between major versions. That’s a good point, I will need to look into how that is functioning now and how we would like it to.

grasmash’s picture

@jonathanshaw It looks like the current /documentation landing page is actually missing a search box. This is why it was accidentally dropped when we moved from wireframes to a dev implementation. I've opened the following two issues:

#2989334: Add documentation search box to /documentation
#2989335: Add a "major version" field and search facet for documentation guides and pages

hansfn’s picture

The mockup in #49 (or in the recent blog post) is nice. I like that you get direct access to each chapter of the User Guide. Just do it!

PS! Have I missed something? I don't know the password/username to https://docinitiative-drupal.dev.devdrupal.org/documentation

jhodgdon’s picture

The popup asking for user name and password should tell you it's drupal/drupal for all dev sites.

hansfn’s picture

I was looking for such a message, but in Chrome (desktop and mobile), the pop-up just asks for username and password. There's no helpful message. (You don't have to reply - if I care enough, I'll create a separate issue.)

wturrell’s picture

@hansfn: FYI it's because Chrome doesn't display the "realm" for basic auth, they've decided it's an "insecure string". (Possibly worth people knowing you can't rely on it appearing in all browsers.)

https://bugs.chromium.org/p/chromium/issues/detail?id=544244#c32
https://codereview.chromium.org/1466473003/

jhodgdon’s picture

Wow, that's true! I don't think that there is anything the Drupal team can do about it, unfortunately. There is a message in the .htaccess file for that site (and all dev sites on *.devdrupal.org) that says to use drupal/drupal. At least in the versions of Firefox and Chrome I have on my Ubuntu machine, Firefox includes the .htaccess message in its popup dialog, but Chrome doesn't. That seems to be a bad decision on Chrome's part. If you want to file an issue, I would do it in Chrome's bug tracker (wherever that is).

Hm... Looking at Apache's tutorial for authentication: https://httpd.apache.org/docs/current/howto/auth.html
It says

The AuthName directive sets the Realm to be used in the authentication. The realm serves two major functions. First, the client often presents this information to the user as part of the password dialog box. ...

Note the "often". Apparently, Chrome no longer presents the AuthName to the user. :(

hansfn’s picture

Thx for all the responses. I was hoping to avoid this thread to sidetrack - he-he. jhodgdon, maybe just delete comments from 64 including this one and update your comment 63 with some more info?

drumm’s picture

Would be good to see either the screenshot from #49, or if there is something more-current, in the issue summary.

svettes’s picture

Issue summary: View changes
eojthebrave’s picture

I've just read through this issue again, and it's not really clear to me what's left to do here. There are a couple of things outlined in the issue summary.

  • Update wireframe #49 with search box use case in the UI
  • Design the page
  • Implement the new landing page at /docs
  • Delete /documentation and redirect to /docs

It looks like the search bar is present on /documentation, so we can probably strike that to-do. And, I think we can also strike "Design the page", as there's an implementation at /documentation now. And at this point it's probably more productive to open new issues for any changes to the design/layout of that page.

That leaves dealing with the /documentation vs /docs URL. Do we still want to have /docs be the canonical URL for the top level documentation landing page? I kind of think it makes sense given we already have /docs/8, and /docs/7, and /docs would lend itself nicely to URL hacking. Thoughts about this?

@svettes or @grasmash do either of you have anything else you think we should tackle before marking this issue as closed?

eojthebrave’s picture

Status: Active » Fixed

I'm going to close this. My previous comment summarizes the current state of the issue. And it's now been 2 years with no activity. Thank you everyone for your work on this. And please continue to suggest improvements to the design of these pages by opening new issues with your ideas.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.