Documentation: Colors: Add withColors readme with a sample.

[jorgefilipecosta]

Description

This PR adds more extensive documentation for the withColors HOC and provides a sample block making use of it.

[chrisvanpatten]

Hey @jorgefilipecosta would you mind if I took a stab at a revision on these docs? I can't push to your PR but I'll branch from it and push a new branch on my fork.

[jorgefilipecosta]

Sure @chrisvanpatten feel free to branch from it 👍 Thank you!

[tofumatt]

@chrisvanpatten Have you had the chance to push your own branch based on these docs? If yes and I missed it: sorry! I just don't see anything linked from this PR and saw this still open in the review queue.

[gziolo]

@jorgefilipecosta what's blocking this one?

[jorgefilipecosta]

I'm not sure if @chrisvanpatten or other person involved in the documentation efforts continued the work in another documentation branch. @chrisvanpatten could you confirm if that's case? If not I will update this PR so we can have new look.

[gziolo]

@chrisvanpatten - it looks like it awaits your feedback :)

@jorgefilipecosta - the docs file will have to be moved to a new location /packages/editor/src/components/colors. I don't see any README.md there.

[gziolo]

@mkaz and @nosolosw - given your experience with tutoruals, would you mind to help with this one? Maybe it should be divided into section to make it easier to grep.

[gziolo]

See above

[oandregal]

I see this is a README of a component, not a tutorial. For these, I like them short and API driven. We could use this README as a testbed for the doc generator package I'm working on at #13329 If I check out that branch, then execute:

node packages/docgen/src/cli.js packages/editor/src/components/colors/index.js

a README with the external API of the component is generated. It needs a bit more work to be ready, but not much!

@jorgefilipecosta would you have the time to pair with me until we find the right output/API for the docgen package so it's useful to auto-generate README files like this? I think having the doc generator ready will help us document components a lot faster than we are now.

[gziolo]

I love this idea of having docs for components controlled by some automation ❤️

[mkaz]

I like the idea of having the documentation with the components but having enough code examples so that is clear what to do. This may require linking or referencing an existing tutorial, so the assumptions of what the user needs to know are clear and discoverable.

Also, I don't mind the longer documentation, I wish I didn't break up the tutorials into so many steps (different pages) I think it might be easier as one long page. Though this is might be more personal preference than anything.

[chrisvanpatten]

After a quick re-read, I agree that I think this is a bit verbose right now and maybe not super clear as a README.

I think a good approach would be to have a README that's more straightforward and terse, with simple examples, and expand on them in a tutorial.

Right now this is almost like a high level design document explaining how it all works, which is interesting but not especially practical.

[jorgefilipecosta]

@jorgefilipecosta would you have the time to pair with me until we find the right output/API for the docgen package so it's useful to auto-generate README files like this? I think having the doc generator ready will help us document components a lot faster than we are now.

Hi @nosolosw, I can dedicate some time to pair with you and move this forward. I would love to help get some automation to generate docs. Thank you for your availability.

Hi @mkaz and @chrisvanpatten thank you for your feedback, I will try to apply some rewrites to get this in better shape.

[aduth]

What's the status of this pull request? Given prior comments about rewriting the documentation toward practical examples, would it be fair to close this and open a new one when that comes to fruition?

[jorgefilipecosta]

What's the status of this pull request? Given prior comments about rewriting the documentation toward practical examples, would it be fair to close this and open a new one when that comes to fruition?

Yes, I guess that's the best path to follow.