Create a "how to" section in the documentation

[pablobm]

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?
  • How to do file processing / parsing?  #1756
• How to override only specific parts of templates.
  • Always render flashes div so you can insert HTML via Javascript #1661
  • Customize search field  #1315
• How to use Administrate with an api_only Rails app.
  • why update request is post action? #1755
• How to add a button to export data to CSV.
  • How to export dashboards as excel（xls xlsx） #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.
  • Reformulate authorization in example app #1998 (comment)
• Create a variation of Field::HasOne that only links to the associated record, instead of displaying it on the show page.
  • Pass option to Field::HasOne to only display specific columns #1877
• How to edit users managed by Devise
  • Editing devise users requires password field to be filled in #495
• How to sort by relationship field
  • How to sort by relationship field #278 (comment)
• Simpler URLs for isolated namespaces
  • ActiveStorage "media library" / dashboards for blobs and attachments #1560
  • Namespaced models not working #1291 (comment)
• Integrating with the gem Globalize
  • Dashboard generator misbehaves with translated content #1668
• Adding custom actions
  • Custom additional action on actions column on index page #1676
  • Adding actions to dashboard #222
• Make Administrate work with API-only apps
  • Couldn't find the New button #958
• How to handle active_record.strict_loading_by_default
  • Incompatibility with strict loading #2563

Done

• How to hide dashboards from the sidebar.
  • We don't document how to hide dashboards from the sidebar #1587
  • ✔️ Done at Add basic how to section to the docs #1781
• How to provide custom search logic.
  • Make search easier to override and adapt to custom use cases #2096
  • ✔️ Done at How to customise the search #2153
• How to scope HasMany tables.
  • https://stackoverflow.com/questions/59059701/rails-administrate-customize-has-many
  • ✔️ Done at Add guide on how to scope has_many relations #2243

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

[nickcharlton]

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]

Some related issues which are related to this area:

• Hiding Dashboards from the Sidebar: We don't document how to hide dashboards from the sidebar #1587
• Providing a good plugin example to build new ones from: We should highlight a plugin as a good example to work with #1601

[c4lliope]

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]

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

[nickcharlton]

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]

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

[pablobm]

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]

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