Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Improving the intro page of the Block Editor Handbook #27400

Closed
paaljoachim opened this issue Dec 1, 2020 · 7 comments
Closed
Labels
Needs Design Feedback Needs general design feedback. Needs Design Needs design efforts. [Type] Developer Documentation Documentation for developers

Comments

@paaljoachim
Copy link
Contributor

paaljoachim commented Dec 1, 2020

As one enters https://developer.wordpress.org/block-editor/ one sees the following:

Screen Shot 2020-12-01 at 15 19 32

Instead of a moving animated gif, it would be helpful to just show Gutenberg screens where different areas are marked similar to these screens. Each image having short text with links to documentation pages that address these areas.

Sections-in-the-Gutenberg-screen

Gutenberg-blocks

Patterns-Gutenberg

Options-Gutenberg

Having a kind of "road map" or "turist map" showing locations of Gutenberg areas and links to where these areas are addressed in the documentation, can be a good start location for a user who enters the Block Editor Documentation looking for some specific information. Instead of having to search one can look at the initial landing page get the "road map" to the correct documentation page and click the link to get to the information.

EDIT: As Marcus mentioned further below. The above example would be better to add to another page. As in not having it as part of the landing page. I do agree on this. In my next comment I share various web sites and how they handle their landing pages.

@paaljoachim paaljoachim added the [Type] Developer Documentation Documentation for developers label Dec 1, 2020
@paaljoachim paaljoachim changed the title Documentation: Improving the intro page of the Block Editor documentation Documentation: Improving the intro page of the Block Editor Handbook Dec 1, 2020
@paaljoachim
Copy link
Contributor Author

paaljoachim commented Dec 1, 2020

Here are some intro pages to other web sites. We can gain some additional inspiration from on how to form the intro page. In addition to the suggestion I added above.

Example from other documentation sites:

Gatsby

https://www.gatsbyjs.com/docs/

Gatsby-docs-intro

Rust

https://doc.rust-lang.org/stable/rust-by-example/index.html

Rust-doc-intro

Github

https://docs.github.com/en

Github-docs-intro

Zurb Foundation

https://get.foundation/sites/docs/

Zurb-docs-intro

EDIT:
Marcus @mkaz mentioned the following for me. So I am adding it it among the various other sites.

The Modern JavaScript Tutorial

https://javascript.info/

Screen Shot 2020-12-09 at 17 03 24

@paaljoachim paaljoachim added Needs Design Needs design efforts. Needs Design Feedback Needs general design feedback. labels Dec 1, 2020
@mkaz
Copy link
Member

mkaz commented Dec 1, 2020

I do like the idea of better introduction to the documentation for Gutenberg, and like the idea of highlighting sections of the editor to take people to that documentation. However, I'm not sure the first page is right for it.

The main segmentation that I've seen for docs is:

  1. User or author centric docs "How do I use the editor to create blog posts?"

  2. Developer centric docs, "How do I create a plugin to extend the Block Editor?"

  3. Contributor centric docs, "How do I contribute back to the Block Editor?"

There is some overlap between (2) & (3) because the Block Editor is built using the same components and pieces used to extend. So I think the mapping exercise showing users what pieces are what, would fall under these segments.

@paaljoachim
Copy link
Contributor Author

I was kinda wondering in the back of my mind if highlighting sections would be natural to have as part of the landing page or if it would be better to include in another page.

For the landing page/introduction page I think we need to include various informative links perhaps like an index of a book to highlight pages in the documentation. So users can quickly click the links and move onward to the information they need.

@JustinyAhin
Copy link
Member

Hi @paaljoachim.

I've been looking at many of the docs you shared and some others, particularly the documentation of React https://reactjs.org/docs/getting-started.html.

I agree with both you and @mkaz shared regarding the structure of the main page. It would be great to have an introduction to the block editor, with some visual guides, as well as some quick links to access specifics parts of the doc. All this in a certain coherence.

Here's a draft of what I came out with https://gist.github.com/ffe7b710adadd9c3627bd6ade1bcd47e. I'll be adding more details to the gist during the day.

Can you take a look at it and tell me what you think? Thanks :)

@paaljoachim
Copy link
Contributor Author

Hi Justin. It looks like a good beginning.

@paaljoachim
Copy link
Contributor Author

There are a few limits to what we can do as the WordPress theme in use has CSS that is a bit messy. Let's aim for what we want to go with and then figure out how close we can get it.

The important part is going through figuring out which links to add to create a good overview of the handbook.

@paaljoachim
Copy link
Contributor Author

paaljoachim commented Jan 22, 2021

As we now have an adjustment in place for the intro page for the Block Editor here: https://developer.wordpress.org/block-editor/ I will go ahead and close this issue. It can of course be used as inspiration for a future iteration. But for now it has served its purpose.

Developer documentation automation moved this from In progress to Done Jan 22, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Needs Design Feedback Needs general design feedback. Needs Design Needs design efforts. [Type] Developer Documentation Documentation for developers
Development

No branches or pull requests

3 participants