How far to take user documentation?

Contribute Site feedback

AI-generated summary

The discussion revolves around the extent of user documentation for Discourse. watchmanmonitor initiated the conversation by referencing eviltrout’s suggestion in pull request 1821 to link to Rails documentation instead of providing detailed instructions. eviltrout believes it’s essential to guide users to the point where they can understand the underlying platform, but then let them learn from the official Rails documentation. watchmanmonitor offered to create a pull request to implement this approach and inquired about a specific part of the Rails documentation to link to, but eviltrout left it to watchmanmonitor to decide.

1

In pull request 1821, @eviltrout asked:

"About rails s: I wouldn’t be against adding it but at what point do we stop holding their hand and expect them to know how rails works? I’m sure rails documentation could do a better job than us. Actually maybe we should just link to that?

What point to stop holding their hand? I guess it’s along the lines of showing a toddler how to walk.. let’m try once they can barely stand up on their own. :slight_smile:

I know that two months ago, I wouldn’t have had a clue what to do at the end of that how-to. Even still, I’m not certain that it’s just a matter of rails s to get started. What other steps need to be added?

2

I do think that leading them into the official rails documentation at that point is not a bad idea. Like “congratulations, everything is ready but now you’ll need to understand the platform we built it in to be productive.”

3

I’d be glad to write a pull request to take use there. Is there a specific part of their documentation you have in mind?

4

Nope but I bet you can find one!