Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
bskinn opened this issue Nov 28, 2022 · 0 comments
Labels
area: docs 📄 issue: planned ⌚ Assigned to a specific version's milestone type: enhancement ✨ Something to add
Milestone

Comments

@bskinn
Copy link
Owner

bskinn commented Nov 28, 2022

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.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: docs 📄 issue: planned ⌚ Assigned to a specific version's milestone type: enhancement ✨ Something to add
Projects
None yet
Development

No branches or pull requests

1 participant