Open pablobm opened 3 years ago
To copy an idea from another community (as I've been doing a bunch of React Native recently), I found React Navigation's set of "Guides" to be pretty helpful: https://reactnavigation.org/docs/getting-started#!
Some related issues which are related to this area:
Looks like @nickcharlton is making good progress; could someone add a link to his page in the documentation sidebar, here? https://github.com/thoughtbot/administrate/blob/a4dcaf339989c14498a921d9a1dc40ac84576d1a/spec/example_app/app/views/layouts/docs.html.erb that way it would show up for beginners who are seeking guidance on https://administrate-prototype.herokuapp.com/.
I also like the name "Guides", "Common Guides", or "Road Map", instead of "How To", and perhaps instead of "Getting Started" - which implies your experience could also be ending soon, we could change that page's name to "Day One" - implying you may be using our library for years to come.
Hm... https://administrate-prototype.herokuapp.com/how_to is broken; has there been a recent deploy on heroku?
The prototype Heroku app will be the last release (v0.14.0
), so if we've made changes since they won't be visible.
But, I created a prerelease which should be current master
.
fwiw, I'm keen on calling it "Guides" too, but it's not something I feel particularly strongly about.
Uh, thank you for that prerelease app. What do you think about linking to it from the README? In the past I've had issues with other libraries where their readme documented master, which differed from the latest version. In this case it's the opposite, but I think it would be useful to those who use master instead of the gem.
Hmm, yeah, I seem to have done it in a few places but not consistently. I've opened #1813 to do this.
I think that our documentation is pretty good for experienced Rails developers, who know the conventions well and just want to get going. However I feel that it falls short for those who are a bit newer to the framework. Many things are left unsaid because they are implied in the conventions of the community. Newcomers are less aware of these and will struggle.
A way to solve this could be to create a "how to" section in our documentation, similar to the one offered by Devise: https://github.com/heartcombo/devise/wiki/How-Tos. These are some initial ideas of articles there, taken from actual questions from users:
api_only
Rails app.new
page.Field::HasOne
that only links to the associated record, instead of displaying it on the show page.active_record.strict_loading_by_default
Done
HasMany
tables.For clarity, I would add this section to the current documentation files, as opposed to a GitHub wiki like Devise does.