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
  • Design the page
  • Implement the new landing page at /docs
  • Delete /documentation and redirect to /docs
CommentFileSizeAuthor
#10 Doc Home - 1.1.jpg546.92 KBjjpoole
Members fund testing for the Drupal project. Drupal Association Learn more

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.