bskinn/sphobjinv

Re-work docs to better highlight the problems sphobjinv solves & how it solves them

Opened this issue · 0 comments

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