Skip to content

Add a beginner-friendly quickstart to docs #47

@jwodder

Description

@jwodder

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?
  • ???

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions