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

Add a quickstart/cookbook with annotated examples #279

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

alamb
Copy link

@alamb alamb commented Feb 18, 2021

Rationale:

Get new users of Snafu going as quickly as possible using the library, by showing the common patterns by example.

I believe that once people see the power of Snafu and use it, they are more likely to invest additional time learning more of how it works, which the rest of the documentation excels at. However, at first they just want to get on with whatever project they are working on with minimal upfront effort.

Change:

This PR proposes to add a quickstart / cookbook at the beginning of the Snafu docs with all the key concepts I would have liked to know as a new Snafu user while working on IOx (and that we have partly codified in https://github.com/influxdata/influxdb_iox/blob/main/docs/style_guide.md#errors)

Notes

The other thing that would be very helpful is to have an API doc somehow for for the generated context selectors but I couldn't figure that out.

For example, I can't find any documentation for the fail function that is on context selectors in the docs:

Screen Shot 2021-02-18 at 6 32 30 AM

Since these types are are generated using macros, my IDE also doesn't help tell me what is available. I realize this may be technically challenging, but I wanted to mention it as something I (still) really want to be able to access but haven't been able to find out.

@alamb
Copy link
Author

alamb commented Feb 20, 2021

FYI @shepmaster

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

Successfully merging this pull request may close these issues.

1 participant