Skip to content

Documentation tweaks #434

@benhutchison

Description

@benhutchison

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions