guardian
Getting started should show how to use the library
Is your feature request related to a problem? Please describe.
The getting started guide shows how to install the library, but not how to use it.
Describe the solution you'd like
A hello world example application that includes the source library would be ideal. If that's too much effort to build and maintain then some examples of setting up a project to use some of the components would give someone a playbook to follow in their own project.
Describe alternatives you've considered
The alternative now is to read the DCR source code. DCR is pretty complex though so it's a challenge for someone to find the parts of the codebase thing if they don't already know where to look. It's easy for the people that already know but that isn't the entire target audience.
Additional context
Imagine a Scala developer builds something during hack day, and wants it to look "on brand". They will already know typescript, but may not have much knowledge of the broader stack. yarn, css-in-js etc. They should be able to use source to get source integrated and working in their project on a hack-day timescale.
Actually, I think the docs on each component probably do address my question. I guess I'd suggest the following:
- renaming getting-started to "installing source"
- or at least mentioning on getting started that usage is with the components so people know to keep looking
I think you've done a great job already :-)
Thanks @adamnfish for looking through the docs and raising this thoughtful and I believe important issue. I don’t think it deserves to be closed and I’ll certainly look to address the points you raise.
I just ran through an imagined user flow of a developer looking at the docs for the first time to confirm. It’s definitely not obvious how to get from installation to up-and-running. I’m going to add this to our backlog and hopefully we’ll smooth out some of those “getting started” bumps.
Feel free to reopen this if you like. Either way I’ll keep you updated via this issue.
I'm reopening this because I think it's a really valid point. The docs are superb and really useful to me but they don't serve the first time user well and we should try to give people fresh to the repo a great experience.
For me, when I consume new libraries my first pass through the docs is typically where I'm on the just-get-it-working journey. I'll come back later for the details or to learn more but on that first visit I want the yarn add ... loud and proud, followed by an example from which I can copy and paste. Most of the time when I land on lib pages, my mind automatically tunes out text with a white background and zones in on the juicy grey background stuff.
On my second pass, I'm usually looking for a link to 'docs' or 'api'. I will pathologically ignore most navigation and instead just scan for those words. Tbh, theguardian.design isn't the easiest site to navigate, it's a bit all or nothing.
After that, once I've loaded the navigation into my head. it's great, and will continue to be great probably for 99% of the time I will use it - but it's nice nice to fix that first 1%.
By the way, congrats on 1.0! 🎉
Hi @adamnfish, @oliverlloyd
I've made some changed to the Developer Guide on the website, notably:
- Added more navigational links to improve the flow through the documentation
- Added a link to the "Components overview" page that serves as an entry point to more detailed documentation for each component
- Added an Example Usage section to the component guide
- Added more detail about peer dependencies
I haven't built an example application to show how to get up and running, but I'm hoping that the example-rendering template repo could become that. Thoughts on this welcome.
Please would you be able to take another run through the developer guide if you have time, and let me know if you still think it needs some work?
As an update to this I've also created the Source Welcome Pack 🤗 🎊 🤝 (internal only) to present to new starters and people who are exploring Source for the first time. The goal is to try and make our onboarding even friendlier: it contains more background info and links to the most important docs pages. I wonder if this would be useful?