search

mozilla / protocol

A design system for Mozilla websites.
https://protocol.mozilla.org/
Mozilla Public License 2.0
261 stars 77 forks source link

Improve Protocol's getting started documentation #376

Open alexgibson opened 5 years ago

alexgibson commented 5 years ago

I recently talked with one of the developers who used Protocol on https://iot.mozilla.org/ and got some good feedback on using design system from the perspective of another team.

Getting started documentation

We don't have any real "getting started" documentation on https://protocol.mozilla.org/. A little extra information would go a long way such as:

This seems like a no-brainer, but if other teams are now using Protocol we should really take the time to add this to the home page.

Boilerplate example

Once they managed to build protocol, creating components was easy enough following the pattern library markup (hooray!). However, they hit a wall asking "Why doesn't the navigation work, and why doesn't the footer collapse on small screens?" After helping to debug, it turned out they we're missing the common protocol-supports.js and protocol-utils.js scripts in their base template, and they were also missing the no-js CSS class on the <html> element. This is all arcane knowledge our team takes for granted. To make this simpler for other teams, we should provide a boilerplate HTML template to copy & paste as part of the getting started documentation (See https://github.com/mozilla/protocol/issues/194)

amychurchwell commented 5 years ago

Information found here: https://github.com/mozilla/protocol/tree/master/docs would be helpful for this section

craigcook commented 5 years ago

https://github.com/mozilla/protocol/blob/master/src/pages/docs/contributing.md was recently added but hasn't been published to the doc site yet. There are surely further improvements we can add there.

craigcook commented 3 years ago

Contributing docs were much improved in https://github.com/mozilla/protocol/pull/633/ though there's always more to add. I still like the suggestion of including a boilerplate starter file, which is largely covered by another issue (#194) so I think we can called this one resolved, or at least as resolved as living documentation can ever be.

craigcook commented 3 years ago

On second thought, the contributing docs are focused on adding TO Protocol, not so much how to use it on your own project. That still needs to be documented, so reopening.