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
Comments
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: Gatsbyhttps://www.gatsbyjs.com/docs/ Rusthttps://doc.rust-lang.org/stable/rust-by-example/index.html GithubZurb Foundationhttps://get.foundation/sites/docs/ EDIT: The Modern JavaScript Tutorial |
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:
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. |
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. |
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 :) |
Hi Justin. It looks like a good beginning. |
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. |
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. |
As one enters https://developer.wordpress.org/block-editor/ one sees the following:
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.
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.
The text was updated successfully, but these errors were encountered: