Getting Started Documentation Feedback #4433
thescientist13
started this conversation in
General
Replies: 1 comment 1 reply
-
Hey Owen! Thanks so much for taking the time to put this together. Great timing - you may have seen we're updating our Getting Started documentation! May ping ya some thoughts/questions here as we dig in, if that's okay :) |
Beta Was this translation helpful? Give feedback.
1 reply
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Hello 👋
I've been following along with this project for a while and had wanted to help test out the
3.0.0-beta
release (though this feedback still applies to the2.x
line as well), and so having a had chance to do so, wanted to share some general feedback with you based on my experience integrating an example component (Accordion) as a first time user. Please bear with me. 🙏Compiling SASS
It has been a while since I had used SASS so my familiarity with its syntax is a bit rusty, but in Phase 2 for developers, the code suggested using
@include
:However, I was only able to get it work with
@import
, which seems right to me in this scenario? I believe@include
is part of using mixins which doesn't seem to be the case here? So wasn't sure if the docs should be changed? Or I could just be completely getting the implementation wrong. 😅Also, should the path to the USWDS source include the file extension too?
USWDS JavaScript
In order to get the Accordion to work, I had to include the USDWS's JavaScript. (naturally)
However, in the Getting started for developer section or the Accordion docs, I don't see a reference to this JavaScript. I had to inspect the network calls of the Accordion demo to find the JS and then found that that in node_modules.
Where would this information be located? Might it make sense to have JS docs linked to from the component docs if they are somewhere? Closest link I could find was for Packages but that only seems to cover the CSS? 🙈
I do see that there is a bundle file is set as the
main
andmodule
entry points in package.json so seems like usage via ESM is an option?Using
files
in package.jsonJust an observation from installing the package and looking around in it, but it looks like all files from the repo are published to npm?
% ls -la node_modules/uswds total 224 drwxr-xr-x 27 owenbuckley staff 864 Dec 11 18:42 . drwxr-xr-x 594 owenbuckley staff 19008 Dec 11 18:42 .. -rw-r--r-- 1 owenbuckley staff 57 Dec 11 18:42 .browserslistrc drwxr-xr-x 3 owenbuckley staff 96 Dec 11 18:42 .circleci -rw-r--r-- 1 owenbuckley staff 206 Dec 11 18:42 .codeclimate.yml -rw-r--r-- 1 owenbuckley staff 16 Dec 11 18:42 .eslintignore -rw-r--r-- 1 owenbuckley staff 8 Dec 11 18:42 .nvmrc -rw-r--r-- 1 owenbuckley staff 116 Dec 11 18:42 .nycrc -rw-r--r-- 1 owenbuckley staff 80 Dec 11 18:42 .prettierignore -rw-r--r-- 1 owenbuckley staff 5791 Dec 11 18:42 .snyk drwxr-xr-x 5 owenbuckley staff 160 Dec 11 18:42 .storybook -rw-r--r-- 1 owenbuckley staff 269 Dec 11 18:42 .stylelintrc.json -rw-r--r-- 1 owenbuckley staff 7948 Dec 11 18:42 CONTRIBUTING.md -rw-r--r-- 1 owenbuckley staff 7207 Dec 11 18:42 LICENSE.md -rw-r--r-- 1 owenbuckley staff 29125 Dec 11 18:42 README.md -rw-r--r-- 1 owenbuckley staff 1673 Dec 11 18:42 SECURITY.md -rw-r--r-- 1 owenbuckley staff 92 Dec 11 18:42 _config.yml drwxr-xr-x 3 owenbuckley staff 96 Dec 11 18:42 config drwxr-xr-x 10 owenbuckley staff 320 Dec 11 18:42 dist drwxr-xr-x 3 owenbuckley staff 96 Dec 11 18:42 docs drwxr-xr-x 15 owenbuckley staff 480 Dec 11 18:42 gulp-tasks -rw-r--r-- 1 owenbuckley staff 2280 Dec 11 18:42 gulpfile.js -rw-r--r-- 1 owenbuckley staff 6098 Dec 11 18:42 package.json -rw-r--r-- 1 owenbuckley staff 3149 Dec 11 18:42 patternlab-config.json drwxr-xr-x 16 owenbuckley staff 512 Dec 11 18:42 security drwxr-xr-x 19 owenbuckley staff 608 Dec 11 18:42 src -rw-r--r-- 1 owenbuckley staff 297 Dec 11 18:42 tsconfig.json
Wasn't sure if this was intentional for a certain set of users but depending on the applicability of that use case, it might make sense to use the
files
field to better scope what gets published to npm?This would help avoid packing extraneous files users will never need / use and requiring them to download them all the time. Also for debugging in node_modules it is nice to have just the files published to help focus on just the files that matter.
Let me know your thoughts, I definitely feel comfortable opening PRs for all of these if you are so inclined. Keep up the great work! 💯
Beta Was this translation helpful? Give feedback.
All reactions