Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation tweaks #434

Open
benhutchison opened this issue Feb 22, 2023 · 1 comment
Open

Documentation tweaks #434

benhutchison opened this issue Feb 22, 2023 · 1 comment

Comments

@benhutchison
Copy link

benhutchison commented Feb 22, 2023

This is some feedback on two small ways Coulomb docs could be slightly more beginner friendly.

It's no exaggeration to say that Coulomb has a lengthy learning curve. There are a lot of details to learn and remember to use the library fluently and productively. I have 15 years with Scala and am already convinced of the value proposition, and yet it's been challenging to adopt Coulomb practically in a "real world" codebase.

  1. Revise key imports on the Concepts page.

    The Introduction page includes a section on imports. However, for the first year of use, a programmer will be spending a lot of time on the Concepts page which contains a lot of key documentation. I find myself often flicking back to the intro just to grab the imports again. So I suggest a small section that revises the assumed imports at the top of Concepts.

  2. Mention Unitless quantities. Scalars play a very important role in most domains. When embracing units, it's important to know how to "turn them off". A paragraph with an explanation of unitless quantities and how to simplify canceling units back to unitless would be useful. Eg The use of literal type 1 for scalars might be surprising to newcomers.

@erikerlandson
Copy link
Owner

@benhutchison good point, I never included a discussion of unitless values, which I had planned to do

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants