Create a "how to" section in the documentation

pablobm commented 3 years ago

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:

[ ] How to do file processing / parsing?
- https://github.com/thoughtbot/administrate/issues/1756
[ ] How to override only specific parts of templates.
- https://github.com/thoughtbot/administrate/issues/1661
- https://github.com/thoughtbot/administrate/issues/1315
[ ] How to use Administrate with an api_only Rails app.
- https://github.com/thoughtbot/administrate/issues/1755
[ ] How to add a button to export data to CSV.
- https://github.com/thoughtbot/administrate/issues/1520
[ ] How to add functionality to import data from CSV.
- https://stackoverflow.com/questions/66247220/best-way-to-do-csv-seed-file-upload-to-rails-repo-through-administrate
[ ] How to add a "create and add another" button in the new page.
[ ] How to add authentication and make it work with the existing authorization facility.
- https://github.com/thoughtbot/administrate/pull/1998#issuecomment-907576069
[ ] Create a variation of Field::HasOne that only links to the associated record, instead of displaying it on the show page.
- https://github.com/thoughtbot/administrate/issues/1877
[ ] How to edit users managed by Devise
- https://github.com/thoughtbot/administrate/issues/495
[ ] How to sort by relationship field
- https://github.com/thoughtbot/administrate/issues/278#issuecomment-995654528
[ ] Simpler URLs for isolated namespaces
- https://github.com/thoughtbot/administrate/issues/1560
- https://github.com/thoughtbot/administrate/issues/1291#issuecomment-1270105885
[ ] Integrating with the gem Globalize
- https://github.com/thoughtbot/administrate/issues/1668
[ ] Adding custom actions
- https://github.com/thoughtbot/administrate/issues/1676
- https://github.com/thoughtbot/administrate/issues/222
[ ] Make Administrate work with API-only apps
- https://github.com/thoughtbot/administrate/issues/958
[ ] How to handle active_record.strict_loading_by_default
- https://github.com/thoughtbot/administrate/issues/2563

Done

[x] How to hide dashboards from the sidebar.
- https://github.com/thoughtbot/administrate/issues/1587
- :heavy_check_mark: Done at https://github.com/thoughtbot/administrate/pull/1781
[x] How to provide custom search logic.
- https://github.com/thoughtbot/administrate/pull/2096
- :heavy_check_mark: Done at https://github.com/thoughtbot/administrate/pull/2153
[x] How to scope HasMany tables.
- https://stackoverflow.com/questions/59059701/rails-administrate-customize-has-many
- :heavy_check_mark: Done at https://github.com/thoughtbot/administrate/pull/2243

For clarity, I would add this section to the current documentation files, as opposed to a GitHub wiki like Devise does.

nickcharlton commented 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#!

nickcharlton commented 3 years ago

Some related issues which are related to this area:

Hiding Dashboards from the Sidebar: https://github.com/thoughtbot/administrate/issues/1587
Providing a good plugin example to build new ones from: https://github.com/thoughtbot/administrate/issues/1601

c4lliope commented 3 years ago

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.

c4lliope commented 3 years ago

Hm... https://administrate-prototype.herokuapp.com/how_to is broken; has there been a recent deploy on heroku?

nickcharlton commented 3 years ago

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.

nickcharlton commented 3 years ago

fwiw, I'm keen on calling it "Guides" too, but it's not something I feel particularly strongly about.

pablobm commented 3 years ago

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.

nickcharlton commented 3 years ago

Hmm, yeah, I seem to have done it in a few places but not consistently. I've opened #1813 to do this.

thoughtbot / administrate

Create a "how to" section in the documentation #1778

Done