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

Docs: new intro, principles, and "block as interface" #10216

Merged
merged 4 commits into from Oct 3, 2018

Conversation

Projects
None yet
7 participants
@mtias
Contributor

mtias commented Sep 27, 2018

This is the start of some reorganization of the handbook documents to encompass a more living resource spanning project vision, interface guidelines, all the way down to the API documentation, references, and tutorials.

Kudos to @alexislloyd for the help in getting these started.

A rethinking of the IA of the handbook navigation will also be required separately to give some better hierarchy and clarity to the now quite huge sidebar.

I'm also moving the logo and design resources to the "references" document as it didn't seem worth the front-page.

Let's discuss!

cc @jasmussen @karmatosed @kjellr @chrisvanpatten

mtias added some commits Sep 27, 2018

Rework introduction readme for the handbook.
Start explaining the overall vision and goals a bit better. Also moves resources to the "reference" file.
@kjellr

This comment has been minimized.

Show comment
Hide comment
@kjellr

kjellr Sep 27, 2018

Contributor

This is great. 👏 I especially like the way it frames Gutenberg for both users and designers/developers in the principles section.

I think the first part of blocks.md could use some smoothing over — It's a little hard to parse currently. But I'll hold off on minute comments until someone has a chance to do a more thorough pass at the copy.

I'm also moving the logo and design resources to the "references" document as it didn't seem worth the front-page.

👍 Good move.

Contributor

kjellr commented Sep 27, 2018

This is great. 👏 I especially like the way it frames Gutenberg for both users and designers/developers in the principles section.

I think the first part of blocks.md could use some smoothing over — It's a little hard to parse currently. But I'll hold off on minute comments until someone has a chance to do a more thorough pass at the copy.

I'm also moving the logo and design resources to the "references" document as it didn't seem worth the front-page.

👍 Good move.

@jasmussen

This comment has been minimized.

Show comment
Hide comment
@jasmussen

jasmussen Sep 28, 2018

Contributor

I love it. I think it's such a vast improvement over what's there, I almost think we should get this in wholesale and do corrections after the fact rather than keep this in limbo. It's solid.

I do think the GIF (https://cldup.com/kZXGDcGPMU.gif) could potentially be polished a little bit, showing something a little more exciting, perhaps the slash command and an exciting block, maybe with a better framerate and no mouse clicks visible. But that's a small niggle, and something I can do in a weeks time or so if there are no other takers.

Contributor

jasmussen commented Sep 28, 2018

I love it. I think it's such a vast improvement over what's there, I almost think we should get this in wholesale and do corrections after the fact rather than keep this in limbo. It's solid.

I do think the GIF (https://cldup.com/kZXGDcGPMU.gif) could potentially be polished a little bit, showing something a little more exciting, perhaps the slash command and an exciting block, maybe with a better framerate and no mouse clicks visible. But that's a small niggle, and something I can do in a weeks time or so if there are no other takers.

@mtias

This comment has been minimized.

Show comment
Hide comment
@mtias

mtias Sep 28, 2018

Contributor

Yes, agreed. Would you rather leave the gif out for now?

Contributor

mtias commented Sep 28, 2018

Yes, agreed. Would you rather leave the gif out for now?

@chrisvanpatten

This comment has been minimized.

Show comment
Hide comment
@chrisvanpatten

chrisvanpatten Sep 28, 2018

Contributor

A more comprehensive "meet Gutenberg" video might be nice in place of the GIF. A video can have an audio track and captions, and can also be streamed instead of downloaded wholesale (#webperf), paused, etc. I think for this case a video is probably the better long term option. Definitely not a blocker to merge to be clear, but I think it would provide a much better UX.

I also think this is a great starting point and worth merging now and iterating later 🚢

Contributor

chrisvanpatten commented Sep 28, 2018

A more comprehensive "meet Gutenberg" video might be nice in place of the GIF. A video can have an audio track and captions, and can also be streamed instead of downloaded wholesale (#webperf), paused, etc. I think for this case a video is probably the better long term option. Definitely not a blocker to merge to be clear, but I think it would provide a much better UX.

I also think this is a great starting point and worth merging now and iterating later 🚢

Show outdated Hide outdated docs/reference.md Outdated
@jasmussen

This comment has been minimized.

Show comment
Hide comment
@jasmussen

jasmussen Sep 28, 2018

Contributor

Yes, agreed. Would you rather leave the gif out for now?

No strong blocking opinions. If anyone has bandwidth to create a better GIF, cool. If not, I'll try and get some bandwidth myself.

Contributor

jasmussen commented Sep 28, 2018

Yes, agreed. Would you rather leave the gif out for now?

No strong blocking opinions. If anyone has bandwidth to create a better GIF, cool. If not, I'll try and get some bandwidth myself.

@mcsf

mcsf approved these changes Oct 3, 2018

@mtias mtias merged commit 3867fac into master Oct 3, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@mtias mtias deleted the add/docs-guidelines-intro branch Oct 3, 2018

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Oct 3, 2018

Member

Was it intentionally not included in manifest config file to avoid having it exposed in Gutenberg handbook?

Member

gziolo commented Oct 3, 2018

Was it intentionally not included in manifest config file to avoid having it exposed in Gutenberg handbook?

@mtias

This comment has been minimized.

Show comment
Hide comment
@mtias

mtias Oct 4, 2018

Contributor

Indeed, don't want to have to change urls too much.

Contributor

mtias commented Oct 4, 2018

Indeed, don't want to have to change urls too much.

@mtias mtias referenced this pull request Oct 12, 2018

Open

Handbook Master Thread #10549

2 of 10 tasks complete
@karmatosed

This comment has been minimized.

Show comment
Hide comment
@karmatosed

karmatosed Oct 15, 2018

Member

Really awesome to see this!

Member

karmatosed commented Oct 15, 2018

Really awesome to see this!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment