Improvements to Existing Docs (tracking issue)

[jtoar]

Improvements to Existing Docs (tracking issue)

The following's a list of all the docs we got, what they're about or should be about, and questions/helpful information. I'll continue to update it as things progress:

• [x] App Configuration: redwood.toml: Should list all the configuration options and detail certain setups (e.g. container/vm). Should discuss the importance of the file in identifying a redwood project as a redwood project. The concept of sides/targets is intrinsic to this file, so there's some room for explanation / discussion about the future.
  • This is only for the dev environment right?
  • Are there other ways to configure your app besides toml file? If so then this file should talk about them? Or this file's just about redwood.toml? Just about configuring the dev environment? There's netlify.toml, but we won't talk about that here?
• [ ] Assets and Files: Should detail the two ways to add assets to a Redwood app, pros/cons of each, or moreover, when you'd want to use each one. Could use more examples.
• [ ] Authentication: This is one of those docs will only get bigger and bigger. We might want to look into adding mdx-like "tabs" at some point? I.e., tabs that let you switch between providers--to avoid having an infinitely long doc.
• [ ] Builds: Should...?
• [ ] CLI Commands: All reference right now; should feature more of a usage section--e.g., CLI basics. Need to go into more detail on generators, especially the sdl--where we plan on drawing the line in schema.prisma <-> sdl support...
• [ ] Connection Pooling: Combine with Local Postgres Setup into "Database" doc?
• [x] Contributing: Existing content stays in the framework root. This should just be a short overview, helping readers make the context switch from developing to contributing by linking to the package-agnostic contributing readme and each package's readme in turn. The tone should be encouraging! And besides coding, should highlight helping others on Forums or Issues, Documentation as contribution ways.
• [ ] Environment Variables: Should...?
• [ ] Form: A model of we're striving for. This one's extremely detailed.
• [ ] Local Postgres Setup: Combine into with Connection Pooling into "Database" doc?
• [ ] Router: Another great doc/model. Should probably remove sections about installation/use outside redwood apps?
• [ ] Serverless Functions: Should...? Also see the Custom Function cookbook...
• [x] Webpack Configuration: This one's a little more outright how-to than reference--how to configure webpack. We could do some explanation though; it might be helpful to know what not to override, etc. There's already some examples here.

Taking on a Doc

Please read the working guidelines: https://github.com/redwoodjs/redwood/issues/332

All the docs on redwoodjs.com have a context: they're for developing. They're here to help people develop apps using Redwood.

Before you take on a doc, you should read Router and Form; they have the kind of content you should be striving for. They're comprehensive yet conversational. The one thing they don't have that would be nice is some kind of table, or other easy way of see everything the Router/Form can do at a glance, especially for readers coming back trying to answer the question "what was that one thing again...?" S+ search would also help with this.

Don't be afraid to go into too much detail. We'd rather you err on the side of too much than too little. Also, feel free to suggest a change to the title. If you do though, you'll want to keep in mind searchability and ensure you’re not breaking any links.

Some of the docs need more than others. Some just need a table or two for reference; others are pretty bare and basically need to be written from the ground up. If the doc you're taking on is the latter case, I'd recommend searching the forum/github for prior art--what are people talking about where this comes up?

[weaversam8]

The one thing they don't have that would be nice is some kind of table, or other easy way of see everything the Router/Form can do at a glance, especially for readers coming back trying to answer the question "what was that one thing again...?" S+ search would also help with this.

I think this is a major gap... The Router Docs probably have 10-20 sections. At the very least, I think we should include a list of sections at the top of the page. Laravel Docs do this and it looks like this:

Personally, I also think these sections can/should be listed on the left sidebar as well (only for the current page) but I think that's slightly less important than a list at the top of the page.

[cannikin]

I’m using markdown-it to parse the docs, which does support generating a TOC from the headings in the doc.

On 1280px+ screens there is a “On this page” nav element on the right that kind of serves as a TOC, although it doesn’t have any hierarchy.

On May 31, 2020, at 8:16 AM, Sam Weaver notifications@github.com wrote:

 The one thing they don't have that would be nice is some kind of table, or other easy way of see everything the Router/Form can do at a glance, especially for readers coming back trying to answer the question "what was that one thing again...?" S+ search would also help with this.

I think this is a major gap... The Router Docs probably have 10-20 sections. At the very least, I think we should include a list of sections at the top of the page. Laravel Docs do this and it looks like this:

Personally, I also think these sections can/should be listed on the left sidebar as well (only for the current page) but I think that's slightly less important than a list at the top of the page.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[jtoar]

@sam Was also about to ask if you found the "On this page" nav helpful?

@cannikin I think indenting would help. Spiked this PR to try it out: are things more readable with indents? https://deploy-preview-163--redwoodjs.netlify.app/docs/authentication

Other than listing sections, there's still the question of some kind of API reference for the docs that could use one. I like what tailwind does. All the class properties are in a compact table at the top:

So in Redwood's case, esp. for something like the form, it'd be nice to have a table or something that shows all the options real quick, somewhere in the doc, whether it's at the top/bottom/middle.

[cannikin]

I like that indent stuff, thanks!

[thedavidprice]

One challenge with the ride sidebar for docs like Router, Forms, and CLI is that your browser does need to be wide for it to be visible. I've even missed it before on my widescreen monitor.

I don't think the solution is to have every doc include a TOC at the top -- this would be redundant in the case of the right sidebar displaying.

But when right sidebar is hidden, having the same content at the top makes a lot of sense. Or could try to do something fancy with a hide/reveal that opens from right. fwiw...

[weaversam8]

Wow yeah, I had no idea that even existed. I keep my tabs on the lefthand side of my browser, so the window is a bit smaller, and I guess that's why. (Indentation is a must though, great work on that PR @jtoar!)

That said, I think that we definitely do need better show/hide logic for that sidebar, or to swap it out for a TOC / merge into the left sidebar. I definitely don't think we should have both.

@thedavidprice - Here's my philosophy when I think about docs:

• Having lots of tiny pages for different things isn't great, because clicking between the pages takes time to load. (even with preloading it isn't perfect...) I tend towards having longer pages (like Redwood has right now) that have everything grouped together in the same topic on one page.
  • Projects that try to do a single long page for ALL documentation are super irritating. Redwood is on the right track with how we're currently splitting documentation.

As far as navigation goes though, I think we can improve.

• A docs site should have a visible hierarchy of sections on each page. The "On this page" widget that we have is a step in the right direction, but even without the visibility concerns, why split it up to be on the right side at all? Why not just nest the hierarchy under the doc title on the left sidebar? Keep everything in one place?

Maybe it's just me, but I definitely prefer something like this:

To this:

FWIW, the actual hierarchy for the section I'm reading in the above example is Frontend > Compiling Assets (Mix) > Working With Stylesheets > Plain CSS

I just really don't like that there are levels that I can't see, and that switching to Frontend > Compiling Assets (Mix) > Working With JavaScript requires me to scroll back to the top of the page to switch sections.

Even if we don't merge the sidebars, we could definitely tweak the breakpoints... there's plenty of room at my resolution to show the right sidebar, if we decide to keep them separate.

[cannikin]

Is this nav really causing people issues or are we getting into bike shedding territory here? 😉 I borrowed the nav paradigm from Tailwind's website and it seems to work superbly well there, I've never found it deficient. One improvement I do see would be to only reload the main content area on navigation, instead of the whole page. I'm working on that now.

I'm using the default breakpoints, which you can change in tailwind.config.css but I don't know if that'll have adverse effects anywhere else. Right now "On this page" is showing at the xl breakpoint. If we switched it to show at l there would need to be some re-configuring of the main body because it'll get really narrow before switching to the m layout if there's an additional couple hundred pixels of nav on the right. xl seemed like a good breakpoint because even on the old 11" Macbook Air a maxed out browser is 1440px. I know not everyone is going to run a fullscreen browser but it seemed like a not-unreasonable default.

Re: Table of Contents—we could add one at the top of all docs, but it only shows if the "On this page" nav is NOT showing...

[jtoar]

@cannikin I like the nav too and use it often. (I also love bike shedding!)

I changed the breakpoint from xl to lg over at #166. I do see that narrowing in the main content, but I think there still might be value in figuring out how to let the "On this page" nav linger where it is a little longer. @weaversam8 does it show up now for you / what do you think?

Re: Table of Contents—we could add one at the top of all docs, but it only shows if the "On this page" nav is NOT showing...

Agreed; and this sounds worth trying out.

[thedavidprice]

🤣

I think it could be slippery re: how we improve/implement (guilty of getting ahead of myself). But the main priority is very relevant --> many pages are a challenge to navigate when the right sidebar is not present. The nav structure you implemented is great. We just need is displayed more! Starting with breakpoint adjustment in #166 is a great+simple way forward!

re: Bikeshedding Remarkably, I've never heard this before. And I probably deserve a t-shirt that just has "Bikeshedder™" on it in BOLD print. 'Cause often super guilty.

But at first, I read this as bike "Sledding", which made me think of this: https://www.youtube.com/watch?v=PaZBebMvE8E

[weaversam8]

Yeah, I definitely tend to be pulled into debates about minor styling stuff... I think I tend to be too much of a perfectionist sometimes. I think I still personally prefer merging the nav structure, but this is a fine alternative.

@jtoar - the updated breakpoint shows for me now on the page, thanks.

[jtoar]

@weaversam8 Would you be up for spiking out what this would look like? I think it's hard for me to say without being able to try it out. And all of us here like demos, etc.

Glad to know it's showing up; I'll keep working on that breakpoint.

[cannikin]

I'd support a spike as well, I'm always up for changing my mind in light of convincing evidence!

[weaversam8]

I'm sorry guys, I've been absolutely swamped with work these past few days... I'm still behind, I don't think I have time to spike it out and do a PR, so we can keep it the way it is for now.

I did made a quick mockup in the browser console so I could take this screenshot, in case it helps with vision later on.