Actually I think I just discovered it

[wet monolith]

My takeaway from this is that I badly need to overhaul (at least) the front page of the docs. Thanks for this feedback!

The structure of the docs is a holdover from the original v1 of the project, which focused on compression/decompression at the CLI. Six years on, with the suggest functionality almost certainly being the primary use-case, you're absolutely right that the docs should bring that out more.

I'd be glad for as much feedback on reworking them as you're interested to provide. Thinking about the front page in this light, I absolutely bury the lede the way it's written right now.

Sounds like re-working the front page more along the lines of the README would be a good start.

[prisma jolt]

Yeah, that would be my takeaway as well. 🙂 IMO, the leading goal of a landing page should be concisely but completely addressing (if not comprehensively answering) the questions "What is this", "What can I use it for" and "Why should I use"; summarizing each (particularly the first) and directing the reader to other docs with more information. It sounds like you already are well aware of this and have a good grasp of the issue and what should be done, so my feedback (at least in this aspect) would probably be mostly redundant, but since you asked—

Right now, the first two paragraphs are technical background material delving into the implementation details of .inv and its compression—perhaps more relevant to the tool's original focused purpose, and certainly important background material to have somewhere, but nowadays left to a more detailed explanation on another page, certainly not the top of the frontpage. It then discusses the original use cases for which the tool was developed, in again highly technical language. Likewise, this is probably best left to another explanation page, perhaps alongside the above. In then proceeds to simple installation instructions, which personally I do find appropriate, though it then gets a bit sidetracked with a list of package names on numerous Linux distros and details of optional extras—perhaps this is best left to an Installation and Setup type page.

One possible outline of what you could revise it to say (which again, I presume you're probably already thinking of), is something like:

• 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.)

I highly recommend the Diataxis framework as a way to think about the organization your existing documentation and the user needs it serves, both to help make what's there easier to navigate and better at serving those needs, as well as identifying the main gaps (e.g. missing a beginner tutorial? guides to do specific tasks? an explanation of the technical background? etc) in which you might want to focus on filling.

https://diataxis.fr/

It takes some getting used to, and the most important benefits of it, I find, were not in specifying a rigid system for dividing all docs into four boxes, but a better way to think about how your docs serve reader needs and how they can do a better job of doing so.

[wet monolith]

Yeah, I'm aware of Diataxis and had already started mentally sorting the different pieces of the docs according to the framework. Definitely helpful, especially all they've written about who the audience is, for the various quadrants.

And no, your feedback is definitely not redundant, it's highly appreciated: I'm so saturated in the docs in their current form, it would have taken me quite a while to diagnose what you laid out.

Also, I think you have significant actual expertise as a documentarian...I have a lot of writing background, but I'm very much self-taught on docs and I know I have a lot of room to improve.

[prisma jolt]

I'm not a real documentarian, I just play one on the internet 😂

In all honestly, I'm more or less like you. I have quite a bit of background in technical writing and editing (and would say it's probably my strongest personal skill), but aside from the Diataxis workshops with Daniele, I don't have formal training in documentation either, though it (and related areas) has been one of if not the main focus of much of my FOSS work in the past few years, first writing, editing and maintaining the Spyder documentation https://docs.spyder-ide.org/ (as well as the docs theme, website/blog and website theme), then as a PEP editor and now on the core Python docs team.