Level up documentation

[mjpitz]

The site has largely been a kitchen sink up to this point. It's a good chance to really evaluate the content, pair it down to relevant sections, and focus on the main points.

[mjpitz]

Current Proposal:

• Delete API Services section
• Rename Integrations to User Guides and update content accordingly.
  • GitHub would become Indexing repositories on GitHub, etc.
  • This opens the door for guides on how to connect to different databases as well as any other user guide we may need.
  • Move Command Line under User Guides
• Delete Developing Locally
• Add Concepts or About section
  • Great place for Terminology (Add section on terminology #52)
  • Move Architecture
  • Move Data Model
  • Move Manifest Files

Section Ordering:

• Concepts
• Deployment
• User Guides
• Contributing

[mjpitz]

To better communicate this idea, here's a rough outline of the content with these changes.

- Documentation
  - Concepts
    - Terminology
    - Manifest Files
    - Data Model
    - Architecture
  - Deployment
    - Docker
    - Kubernetes
    - Helm
  - User Guides
    - Exploring using the `deps` CLI
    - Indexing repositories on GitHub
    - Indexing repositories on GitLab
    - Indexing repositories on BitBucket
    - Configuring storage for SQLite
    - Configuring storage for MySQL
    - Configuring storage for PostgreSQL
  - Contributing
    - Code of Conduct
    - Community
    - Working with Git
    - Developing in Docker

[mjpitz]

The landing page could use an uplift as well. I kept things pretty minimal at first, but it seems like there's a good opportunity to improve the landing space for the project. I'll start to dig around for some inspiration on how to elevate some of the content.

[kevindigo]

Generally the proposed ToC looks good to me. I might consider bundling the indexing and storage subsections inside the Deployment section. The audience for those (implementer) seems different from the CLI doc (user). Or perhaps there could be an Installation section, with subsections for Deployment and Configuration. Or maybe it would be Deployment, Configuring Indexing, and Configuring Storage? I don't know enough about the details to have a sense of the specifics.

At a very high level, I think "Introduction", "Using it", "Running it", and "Contributing to it" would make sense as top-level sections. They could be named differently, of course. At that point, I would consider shifting some of the Concepts out of the introduction, especially if they are only of interest to contributors.

The most important subsection for me would be the high level introduction. I'm not sure if you would have that before the Concepts section, or if it should be a subsection of Concepts, right before Terminology. The goal would be to answer the 2 questions "What is this thing? Why might I want to learn more?", asked by someone who doesn't yet know anything about this project. Many (most?) open source projects lack that initial pitch, and it pains me every time. I would be happy to proof, or perhaps even draft, some text for this piece.

[mjpitz]

Generally the proposed ToC looks good to me. I might consider bundling the indexing and storage subsections inside the Deployment section. The audience for those (implementer) seems different from the CLI doc (user). Or perhaps there could be an Installation section, with subsections for Deployment and Configuration. Or maybe it would be Deployment, Configuring Indexing, and Configuring Storage? I don't know enough about the details to have a sense of the specifics.

Completely agree, moving it under Deployment makes sense to me.

The most important subsection for me would be the high level introduction. I'm not sure if you would have that before the Concepts section, or if it should be a subsection of Concepts, right before Terminology. The goal would be to answer the 2 questions "What is this thing? Why might I want to learn more?", asked by someone who doesn't yet know anything about this project. Many (most?) open source projects lack that initial pitch, and it pains me every time. I would be happy to proof, or perhaps even draft, some text for this piece.

Also completely agree. I intentionally left mine off because I was still trying to figure out the right target and pitch. Definitely open to recommendations and any drafts you're willing to offer.

[mjpitz]

Here's another pass at an outline:

- Documentation
  - Concepts
    - Terminology
    - Manifest Files
    - Data Model
    - Architecture
  - Deployment
    - Docker
    - Kubernetes
    - Helm
    - Configuration
      - Storage
        - SQLite
        - MySQL
        - PostgreSQL
      - Indexing
        - GitHub
        - GitLab
        - BitBucket
  - User Guides
    - Command Line
    - Python SDK
    - NodeJS SDK
    - Golang SDK
  - Contributing
    - Code of Conduct
    - Community
    - Working with Git
    - Developing in Docker

[mjpitz]

Alright. I've got a pull request out with the restructure of content. I marked pages as drafts where appropriate and I'm going to go through and start breaking out tickets to fill in each of the sections that are still marked as a draft.