[TRACKING] ViewComponent documentation site

[joelhawksley]

Summary

With Rails 6.1 on the horizon, the ViewComponent project will be under increased attention from the public.

This is a great opportunity for us to make the best first impression possible to the Rails community.

Let's level up our README into a documentation website we'll be proud of!

TODO

• Register domain name (viewcomponent.org)
• Pick out / design Jekyll template
• Move docs from README to site
• Publish site
• Review site content and plan for any additions
• Add quick start to README (move most documentation to docs/index.md #512 (review))

Open questions

• Should we have a logo? ViewComponent needs a logo! #649
• What are some documentation sites we might be inspired by?

[jaredcwhite]

A few Ruby/Rails-aligned documentation sites I'll mention:

• StimulusReflex
• Jumpstart
• Bridgetown (full disclosure — I work on this one)

[joelhawksley]

@jaredcwhite those are all fantastic examples!

I'm really impressed with the Bridgetown site. Would you be up for helping out with this project?

[jaredcwhite]

@joelhawksley Well, if you don't mind using Bridgetown rather than Jekyll, I think it'd be pretty easy to clone the BT site and clear out the content and tweak the design for use here. You should be able to use GH actions to run the build process and deploy on pages here… slightly more inconvenient than using Jekyll directly, but not by a ton. (Bonus: you get Webpack for front-end assets as well that way…) Anyway, I could help out with all that if need be.

[g13ydson]

@joelhawksley I really like how things are organized using the gitbook + github integration. I created a documentation reorganizing some subjects by sessions. So, if it looks good, I can open a PR with the gitbook MD files.
https://g13ydson.gitbook.io/view-component-docs

[pinzonjulian]

I'm happy to help out writing any guides or docs!

PS: Love the gitbook site @g13ydson !

[joelhawksley]

@g13ydson very cool! Would we still be able to host this on GitHub pages?

[g13ydson]

@joelhawksley with gitbook it is possible, but it takes more work. I decided to create with Jekyll. #529
DEMO: https://g13ydson.github.io/view_component_doc/

[joelhawksley]

In https://www.youtube.com/watch?v=EQoJVFgZXo4, @maxshelley gave our docs a thorough read as a developer new to the project ❤️

Here are some improvements I think we should look into making based on his experience:

• Add more detail regarding the form_for workaround. I think we can direct folks towards using the _tag helpers for now.
• Provide a better example application experience than view-component-demo, which is out of date and lacks documentation.
• Link to the PVC components and tests as examples.
• Add documentation for the monkey patch.
• Add a brief explanation for why ViewComponent is faster than partials.
• Clarify that content is set by passing in a block, and doesn't need to be an argument in the component initializer.
• Add documentation on how to generate a sidecar folder with the generator.
• Clarify that render? is for whether the entire component is rendered or not.
• Find a better way to explain what is accessible from the component template (instance variables and methods on the component object).

[joelhawksley]

Some resources I plan to reference for this work:

reduxjs/redux#3609
https://stitches.dev/docs/responsive-styles
https://documentation.divio.com
https://news.ycombinator.com/item?id=21289832
https://stoplight.io/blog/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1/
https://stoplight.io/blog/writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a/
https://news.ycombinator.com/item?id=17829751
https://brainhub.eu/blog/writing-good-documentation-open-source-library/
https://dev.to/ojkelly/the-four-layers-to-great-documentation-dj7
https://jacobian.org/series/great-documentation/
https://v3.vuejs.org/guide/contributing/writing-guide.html

[Spone]

I'm starting an evolving list of wanted improvements to the docs:

• explain the use cases for variants, and how to use the feature in regular components
• [...]

[joelhawksley]

Some notes from #684:

• Add a diagram like https://twitter.com/dan_abramov/status/981712092611989509/photo/1 to the Lifecycle page.
• Add _after_compile to Lifecycle.
• Look into higher-contrast syntax highlighting.
• > I think we could put a really convincing example there showing off some of the features of view components as well as the value they provide. - @BlakeWilliams
• Scale back sidecar assets page
• Link to Gov.uk and bootstrap components in Resources

[joelhawksley]

More notes from my RailsConf Q&A:

• Add note for rendering view components outside of controllers and views (jobs, etc)
• In what cases should we use VCs over partials? (No more partials)
• How should VCs be organized and named? (Like controllers, namespaced, etc)
• Have you experienced going back to your exisiting components and re-writing the interface as you use it on more cases?
• How have y'all at Github approached testing view components that have an interactive component to them? We've mainly been unit testing each view component we add and then writing feature specs for browser interactions, but I'm wondering if there is a better way to approach it (System tests, cuprite)

[joelhawksley]

I'm starting an evolving list of wanted improvements to the docs:

• explain the use cases for variants, and how to use the feature in regular components
• [...]

@Spone I've filed this in #898 ❤️

[joelhawksley]

👋🏻 I've split this issue out into sub-issues 🎊