[kough]

I'm totally on board with the "contributions welcome" response from open source maintainers, but when it's the only response to questions about documentation it's pretty off-putting. This is your project, how could you expect a new contributor to add docs without your input? I get that good documentation is hard, and takes time, but if you want your project to succeed I think it's almost mandatory for you to write these docs (at least the initial version!) yourself.

[bphogan]

I have to agree here. There's nobody better to explain how something really works than the person who wrote it. The rest of us are just fumbling around guessing.

As a dev and a creative person, I understand the desire to get something out there. But documentation and tutorials aren't just something that's nice to have. They are your marketing tool, your adoption driver, and the way to create educated advocates for your project. They are as valuable to your project's success as a splashy "getting started" web site is.

[AShedOfTools]

That process of you fumbling around and guessing is actually really extraordinarily helpful. The things a contributor might think to do or to try, and the things that a newcomer might think to do or to try, are completely different. No documentation survives its first encounter with a real newcomer. We can, and will, continue working on the onboarding experience, but we'll need real users to roll up their sleeves and wade into it, and the first few of them will have questions we didn't anticipate, and make assumptions we've never considered, and try use cases we've never thought of. Creating good documentation is something that newcomers and contributors need to collaborate on.

[bphogan]

That process is the second part of the process, once clear, basic documentation exists.

[martco]

To me this product markets itself. This team has accomplished a lot with this tool, and i'm compelled to adopt and educate myself.

The proof (and splash) is in the pudding here. Kudos to dev team that built this.

[AShedOfTools]

I completely agree. If you take a look at the closed prs with the label documentation (https://github.com/redfin/react-server/pulls?utf8=%E2%9C%93&...) I hope you get the sense that this is something that I'm thinking about a lot, and that if you look at the issues open with the same label (https://github.com/redfin/react-server/issues?q=is%3Aissue+i...), that it's something I'm working on actively. There are lots of ways to document a healthy project, from tests to tutorials to docs sites to good examples, and we've been working hard on markdown docs, tests and examples because they allow us to scale to having more contributors faster. Striking a balance between kinds of documentation is hard, and its even harder to strike a balance between the rest of the project's needs and documentation. This is a technology that we run in production, and so we have to make sure that it is fast and stable and reliable, and sometimes that means giving short-shrift to other priorities. I'm not trying to absolve us of any short-comings in our documentation -- we have a lot to do in the coming years to improve this project, and we need to spend time writing tutorials and user testing the on-boarding experience for new devs that want to start up their first React Server project -- but I do want you to understand where we're coming from when we say "contributions welcome." Its just pragmatic; we're working on it as hard and as fast as we can, its a priority I continue to focus on, and if you want it faster, the best way is to chip in.

[kough]

OK, you definitely get it :) Love what you wrote below:

"No documentation survives its first encounter with a real newcomer."

I hope it didn't seem like I was accusing you of negligence – the docs you have are an awesome start, and I fully appreciate the difficulty of the problem. Best of luck with things going forward, looks like a really neat project.

[AShedOfTools]

Aw shucks :) Thanks!

[davidalber]

gigabo's account has been rate limited, but he wants to say:

Oh, hey didn't mean to sound flippant there! We're definitely planning to make tutorials, and we're constantly trying to improve our docs. I guess my point is we want this to happen faster, but we're still a pretty small project with a small team of core contributors. So we're thrilled when we're able to bring in new contributors to help out!

[trjordan]

I don't think that's true. It's certainly possible for somebody else to run with tutorial creation, especially if the project gets attention / exposure before the tutorials are ready.

If the response "Contributions welcome" is generic, it's because the complaint is as well.

[jzelinskie]

"Contributions welcome" is often echoed, but I like to remind colleagues that it is not the proper mentality to foster a real community. You can't just dump code on GitHub and assume the world is going to start firing off PRs to do your dirty work. You have to assume that no one else cares about your project, but being open to changes in code and leadership will make your project more robust to other use cases.