-
Notifications
You must be signed in to change notification settings - Fork 4
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
Level up documentation #53
Comments
Current Proposal:
Section Ordering:
|
To better communicate this idea, here's a rough outline of the content with these changes.
|
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. |
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. |
Completely agree, moving it under Deployment makes sense to me.
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. |
Here's another pass at an outline:
|
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. |
* gh-53: moved configuration under deployment * gh-53: marking storage as a draft * added concepts and guides section, marking drafts where appropriate * gh-53: added section for graph knowledge * gh-53: moved intro content to docs section * gh-53: build out top level navigation * gh-53: reweighted * gh-53: simplified data model and architecture to only convey relavant concepts * gh-53: removed prefix
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.
The text was updated successfully, but these errors were encountered: