Per Discord conversation with @CAM-Gerlach, docs currently are unclear and poorly organized.
This is correct. Indeed, they grew organically from the original v1.0 docs, which were only documenting the convert CLI, to include the new API and the suggest feature.
Time to re-work them, with intentionality. His suggestions, heavily excerpted/summarized:
High level summarize these and point to other places in docs for more info:
What is this?
What can I use it for?
Why should I use it?
Front page:
First two paragraphs are technical background material delving into the implementation details of .inv and its compression
more relevant to the tool's original focused purpose
important background material to have somewhere
more detailed explanation on another page
Then discusses the original use cases for which the tool was developed
best left to another explanation page, perhaps alongside the above
Then proceeds to simple installation instructions, which personally I do find appropriate
Then gets a bit sidetracked with a list of package names on (1) numerous Linux distros and (2) details of optional extras
best left to an Installation and Setup type page
Possible outline for revised front page:
Lede para with a brief description of what a .inv file is and what sphobjinv is (e.g. a package that lets you search and convert .inv files on the command line, and read, write and analyze them from Python)
Bullet point summary of the main features
The current installation guidance
Maybe a single super brief suggest CLI example, like the first one in your readme
Bullet list, table or other construct providing a high-level outline of where the reader can go from here to learn more (tutorials, guides, CLI reference, API reference, learn more about objects.inv, external resources, etc.)
Per Discord conversation with @CAM-Gerlach, docs currently are unclear and poorly organized.
This is correct. Indeed, they grew organically from the original v1.0 docs, which were only documenting the
convert
CLI, to include the new API and thesuggest
feature.Time to re-work them, with intentionality. His suggestions, heavily excerpted/summarized:
High level summarize these and point to other places in docs for more info:
Front page:
Possible outline for revised front page: