versioningit icon indicating copy to clipboard operation
versioningit copied to clipboard

Add a beginner-friendly quickstart to docs

Open jwodder opened this issue 2 years ago • 0 comments

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 avatar Apr 09 '23 21:04 jwodder