Documentation Improvement

[kingdomcoding]

Surface is an amazing project.

I think it'll be helpful if increased attention is given to its documentation.

Specifically, why are there two alternative documentations? Hexdocs and Suface-UI.org? Are they to serve different purposes?

I suggest that investing effort into an improved hexdocs page will suffice.

[tiagoefmoraes]

That will be very helpful.

With surface-ui.org we can have live examples of Surface components, it works as the catalogue but for showing Surface concepts instead of components.

We'll soon release a blog that will be available in surface-ui.org

After that we'll have 4 sources of documentation:

• surface-ui.org
• hexdocs.pm/surface
• blog in surface-ui.org
• catalogue

Each one has it's advantages and disadvantages to different aspects of documentation: tutorial, how-to guide, explanation and reference. We still need to find the right balance on that.

Please contribute in what you find will have the best value to you, it sure will have value to the community.

[simonmcconnell]

I think it could be worthwhile slimming down surface-ui.org and having all the non-demo documentation moved to hexdocs guides? Hexdocs is where people expect it, at least that's where I expected it at first. That said, I rarely look at Surface's hexdocs these days, tending to the website and the source, but do find it hard to find some things on the website.

[msaraiva]

I think it could be worthwhile slimming down surface-ui.org and having all the non-demo documentation moved to hexdocs guides?

I agree.

do find it hard to find some things on the website.

We should address this in the scope of surface-ui/surface_site#65.

[petermueller]

A number of the pages are made up of Markdown components. Would there be an opportunity to use an @external_resource attribute, and extract the content into some .md files in the surface-ui repo that ExDoc can pick up?

Or maybe some iframes on the surface_site to the hexdocs guides😅

Maybe what we need is a kind of rubric or understanding for what we'd want where, or where we'd want people to go for which kind of learning? idk, 😶‍🌫️ just asking questions to see if it helps. Not making suggestions

Edit: to the question of what would be useful to me - I often reference the syntax page, slot page, list of properties, and I imagine going forward the context page. I use Surface every day and it's the majority of our templates. So for me it's more of a quick reference, and some form of search would be nice, ideally relying on hexdocs or the docset for Dash that consumes hexdocs. I also train new people all the time and being able to point them at one place to get started that is more verbose, and then have a reference that they can use afterwards that's quick and to the point is great.