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 beginner-friendly quickstart to docs #47

Open
jwodder opened this issue Apr 9, 2023 · 0 comments
Open

Add a beginner-friendly quickstart to docs #47

jwodder opened this issue Apr 9, 2023 · 0 comments
Labels
documentation Improvements or additions to documentation help wanted Extra attention is needed

Comments

@jwodder
Copy link
Owner

jwodder commented Apr 9, 2023

I think we can all agree that versioningit's documentation can be a bit overwhelming for new users. The only parts of the docs that are directly aimed at new users are the "Installation & Setup" and "Example Configurations" sections from the README & docs landing page, and I fear that these sections don't convey everything a new user would want/need to know. The rest of the docs, meanwhile, are an information-dense feature reference which a new user can easily get lost in. Unfortunately, as the tool's author, I have a blind spot as to what information new users should be presented with first (and how) and what information should be left to the comprehensive reference pages.

I therefore call upon you, dear versioningit users, both experienced & new: If the docs were to gain a "quickstart" page covering (hopefully) all the basic functionality that a new user would need or want to know, what should be in it?


Things that probably belong in a quickstart:

  • A table/list of all available format fields
  • How to use the write method?
  • Useful example configurations with explanatory comments
  • ???

Things that probably don't belong in a quickstart:

  • The library API
  • Writing custom methods
  • Git archive support?
  • Mercurial support?
  • How to use the onbuild method?
  • ???
@jwodder jwodder added documentation Improvements or additions to documentation help wanted Extra attention is needed labels Apr 9, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

1 participant