redwoodjs/learn.redwoodjs.com

Incomplete information in Generators section of the quick-start document

adriatic opened this issue · 10 comments

adriatic commented

The Generators section shows the default UserExample model

image

This visual suggests that the UserExample model is the only content in the file api/db/schema.prisma - when the complete content is this

image

Solution for this exists in many screenshots in the Tutorial doc - use the comment line to indicate that there is additional information above the UserExample model, or even better, show the full content of the api/db/schema.prisma file

clairefro commented

Hi @adriatic ! Can you please make a pull request to clarify your suggestion? Thanks for your vigilance towards tutorial integrity

adriatic commented

Note that this issue is the same as issue 77

I would have created the PR right away if I only knew the answers to two questions (see below) that I asked before:

  1. What is the meaning of the sub-string {3, 7-19} in the string ````javascript {3,7-19}`

image

  1. What is the repository to create the PR against (I am aware of the transition towards. There is a new domain (https://learn.redwoodjs.com/docs/) as well as an old one (https://github.com/redwoodjs/redwoodjs.com) and I am not sure which to use for a given PR
cannikin commented

I specifically say "...comes with a default Model called UserExample..." which is meant to get you to focus on that specific piece of code, rather than worry about the entire file. I don't want to get people bogged down in worrying about the datasource or client since that isn't really pertinent to understanding how the schema works or what a model is. I'm careful to get people to laser focus on the important stuff rather than showing the whole context of everything, which could be overwhelming.

I wouldn't mind a parenthetical "(ignore the rest of the file for now, it's for more advanced configuration stuff)" in that sentence, however.

cannikin commented

What is the meaning of the sub-string {3, 7-19} in the string ````javascript {3,7-19}`

That syntax tells the code highlighter which lines to highlight in the code snippet

What is the repository to create the PR against

This one, learn.redwoodjs.com. On each tutorial page there's an "Edit this page" link at the bottom that'll take you right to the file in Github for easy finding!

adriatic commented

Thanks for "jumping in" Rob. The solution you proposed

I wouldn't mind a parenthetical "(ignore the rest of the file for now, it's for more advanced configuration stuff)" in that sentence, however.

is perfectly fine - even for a person with limited abilities to avoid traps like me.

I may have stated this already: I am creating such issue reports not to harp on your ability to write technical documentation, but rather to address your potential inability to understand what all could be a problem for an RWJS novice.

Hopefully, my level of understanding of RWJS design and code will grow and I will not be able anymore to indicate places where more explanations would be helpful.

adriatic commented

This one, learn.redwoodjs.com. On each tutorial page, there's an "Edit this page" link at the bottom that'll take you right to the file in Github for easy finding!

Thanks, I do know that - my question is based on my observation the complete content of the Docs has not been moved to learn.redwoodjs.com - my original issue above describes the document that still lives in https://redwoodjs.com/docs/quick-start.

So, should reporting such issues be postponed until all docs are moved to learn.redwoodjs.com?

clairefro commented

based on my observation the complete content of the Docs has not been moved to learn.redwoodjs.com

This is understandably confusing as we transition.

For now, any suggested changes to content should be PRed to these repos respectively based on content:

Tutorials         >    "learn.redwoodjs.com"
Everything else   >    "redwoodjs.com"

We are working on clarifying this

adriatic commented

Thank you @clairefro for the explanation 😄

adriatic commented

@clairefro wrote

Thanks for your vigilance towards tutorial integrity

@clairefro, I love your description of my obsession. It (my obsession) comes from a lot of bad experiences with incomplete/inaccurate/unclear technical documentation, most being the consequence that people who write the document use the style then best suits the developers who wrote the product being described. In most of such cases, I was the person in charge of software development, and I still could not explain to my team that they cannot put themselves in the shoes of a new user. In all honesty, @cannikin is a rare exception to this rule; however, even his documents left me puzzled sometimes, which might be the consequence of my own limitations.