Note: This post is referring specifically to the Docs section of the Docs, not the entire documentation site with the roadmap, both tutorials, etc.
As we’re growing our documentation it’s started to get a little unwieldy, particularly in the catch-all “Docs” section. (As a larger meta-point, having a Docs section of the docs doesn’t really make a ton of sense to me).
Right now we’ve got 25 sections. In my mind I could imagine breaking this list down to a couple different categories. These lines will be fuzzy and I’d love to get others thoughts on this particularly @dom@rob@thedavid@mojombo@clairefro
Here’s my broad view right now, I think you could potentially made a further distinction in the concepts category between:
Mostly prose explanations
More like comprehensive API documentation
But the more important categorization for me is between config and concepts, with concepts being long form explanatory content and config being targeted instructions for specific edge cases.
And lastly I think Contributing should be as easy to find as possible and right now putting it in the middle of this list makes it unlikely the people who need it most will find it.
Right now our Docs are kind of a mixture of “reference” (like Docs - CLI Commands : RedwoodJS Docs ) and explanation (like Docs - Assets and Files : RedwoodJS Docs ). Some of the READMEs in the individual packages probably count as explanation as well, they explain how to contribute to that specific package.
So far we’ve been pretty good on organizing the “tutorials” and “how-to guides” (cookbook) though!
When I see someone with what appears to be really organized docs (like Introduction to Apollo Server - Apollo Server - Apollo GraphQL Docs ) I find trying to navigate to something manually is basically impossible (“where do I find lifecycle events for a GraphQL request?”) and just default to search.
Our search has a ton of potential for tuning, I’m just using the barest functionality that Algolia provides. @dom was going to look into starting to optimize results at one point. I’d be happy to give anyone access to the Algolia Dashboard if they want to poke around and see about improving accuracy. We have a separate index for branch deploys (and dev deploys) so you could mess around locally without breaking the real site search.
I’m not sure what I really think about this yet, but I don’t want to delay responding forever so I’ll just give some of my thoughts as they are:
→ Making Contributing easier to find makes a ton of sense!
→ We could definitely have more straight-up reference resources (e.g. what props can I pass to <Route />? right now it’s kind of hard to find that information)
→ replying to
As a larger meta-point, having a Docs section of the docs doesn’t really make a ton of sense to me
I don’t think of Docs as a section of the docs. They’re just docs. They’re just in the “root directory”, so to speak.
We used to have “Guides” and “Reference”: https://deploy-preview-144--redwoodjs.netlify.app/. I think the reason we combined them was because we can’t seem to stop explaining things. But that’s also why (imho) we have good docs.
In general, the way I approach writing Docs is:
what’s the topic? E.g., the Router, Storybook, Mocking GraphQL Requests.
Then I just write about it; covering the space of possibilities, as much as I can. And that means reference + explanation. Reference → what you can do, what’s possible. Explanation → value judgements, why we made it this way, how you should actually use it.
Appreciate the thoughts, Dom! This was mostly me wanting to write down and structure my own mental model of the docs and see if anyone had similar ways of breaking it down since it’s a fairly long list and will likely be getting longer.
I’ve seen Tom post the divio link before and I think it’s great and basically maps to what my categories are:
I need to be very careful not to shoot myself in the foot by virtue of overextending my already promised work on documentation for Windows developers. I do not have all information needed to prioritize general documentation navigation over the Windows developers documentation, however my impression of that the first one prevails because of Rob’s statement “Our search has a ton of potential for tuning, I’m just using the barest functionality that Algolia provides”
Suggestions from the RWJS management or other people with a better sense for overall priority would help here.