Redescribed #2255

c4lliope · 2022-08-24T20:39:15Z

Hello; hope all's good.
I looked back across our docs, and I can see much of the language is unchanged from the original,
produced around six years ago. I'm sure my speaking and manner of expression has changed much since,
and so should the composition of our code's guides.

I am going through and re-describing our code, as a means of reminding my preoccupied brain.
Once done on our docs / guides, I am hoping I can begin proposing an agenda of changes to be included in 0.19.0 and 0.20.0;
I am hoping these couple releases can be used as a gauge of 1.0-readiness,
and in some places break up old logic so more concise phrasings can be used.

Alongside a 1.0 (or any planned upcoming) release, I'd like to begin discussing a possible change of this library's name.
"Administrate" is nonsense based on the phrase "Administration", and has been a solid choice for many years.
Regardless, there is a chance to more clearly describe our engine.
I am hoping a change in name can spur some more clear direction in deciding on our engine's use cases.

In such direction, I booked the rubygems enroll and enrolled as possible options.
These names recommend an impression of a leader of a group or class, checking names and addresses on a clipboard.
I imagine a similar scene upon seeing any one of our dashboards, laid up in precise lines summarizing a user's records.
The purpose of a user's dashboard code is the "enrolling" of models, so our engine can handle displays and actions.

c4lliope · 2022-08-25T16:59:30Z

Alongside a release roadmap - I am making a summary page describing our plugins;
see https://rubygems.org/search?query=name%3Aadministrate (73 in all!)

Perhaps some more commonly-used plugins can be pulled inside our main codebase,
and repackaged as core engine use cases.

pablobm

Hello @c4lliope, fancy seeing you around :-)

Thank you for that revamp of the README. I have left some comments; in general I agree that it can be improved.

Re: a potential name change, personally I am hesitant about it. I feel that, when people go searching for engines such as this one, "administration" is one of the top (if not the top) word that comes to mind.

A piece of evidence on this would be the section Rails Admin Interfaces at https://www.ruby-toolbox.com. Administrate is listed there alongside other gems that occupy a similar space, and the word "admin" is common to many of them.

Additionally, I feel that a name change would cause confusion among users, and would lose the recognition that Administrate already has as a name, which is not huge, but still sizeable enough that I have come across many people in the Rails community that knew of it.

I'm curious, what motivated you to think about a potential rename? Perhaps there are reasons that I'm failing to see.

pablobm · 2022-09-29T13:06:17Z

README.md

@@ -5,83 +5,97 @@
 [![Code Climate](https://codeclimate.com/github/thoughtbot/administrate/badges/gpa.svg)](https://codeclimate.com/github/thoughtbot/administrate)
 [![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)

-A framework for creating flexible, powerful admin dashboards in Rails.
-[Try the demo][demo].
+Our engine helps you manage records in your Rails program.


I feel that words like "our engine" and "(it) helps" are unnecessary. This is the one-line description and it already implies them:

Suggested change

Our engine helps you manage records in your Rails program.

Manage records in your Rails app.

(Also I like "app" over "program", as I rarely hear Rails apps called "programs").

pablobm · 2022-09-29T13:07:42Z

README.md

-A framework for creating flexible, powerful admin dashboards in Rails.
-[Try the demo][demo].
+Our engine helps you manage records in your Rails program.
+[See a copy running online][online].


I feel that "copy" doesn't quite convey its nature: it's a demo, and users can visit it and mess with it.

Suggested change

[See a copy running online][online].

[See a demo in action][online].

pablobm · 2022-09-29T13:08:23Z

README.md


-### Warning:
+### Danger: breaking changes are common.


I feel that "danger" is too strong a word. Like it could break your computer or something.

Suggested change

### Danger: breaking changes are common.

### Warning: breaking changes are common.

pablobm · 2022-09-29T13:09:31Z

README.md

-and there may be occasional breaking changes to the API.
-Check the [release notes] for important updates.
+Administrate remains pre-1.0,
+and breaking changes can occur as our designs respond


Perhaps it's my not being a native speaker, but I feel that "evolve" communicates the meaning better:

Suggested change

and breaking changes can occur as our designs respond

and breaking changes can occur as our designs evolve

pablobm · 2022-09-29T13:10:48Z

README.md

-[release notes]: https://github.com/thoughtbot/administrate/releases
+Please pin on a "minor version" number,
+should you need a more reliable application build.
+Make sure you see remarks included in our [release log],


Perhaps it's my non-native ways again, but this looks better to me:

Suggested change

Make sure you see remarks included in our [release log],

Make sure you read our [release log],

pablobm · 2022-09-29T13:13:54Z

README.md

+super-user dashboards across a broad range
+of program shapes and sizes.


Similar app/program distinction (plus what I feel is more natural wording):

Suggested change

super-user dashboards across a broad range

of program shapes and sizes.

super-user dashboards across apps of

all shapes and sizes.

pablobm · 2022-09-29T13:17:47Z

README.md

+Administrate had been preceded by [Rails Admin] and [ActiveAdmin],
+and has been inspired in many areas by such approaches.
+Administrate yearns for a more simple, common-ground approach
+in describing and accomplishing common program use cases.


Suggested change

Administrate had been preceded by [Rails Admin] and [ActiveAdmin],

and has been inspired in many areas by such approaches.

Administrate yearns for a more simple, common-ground approach

in describing and accomplishing common program use cases.

Administrate is inspired by [Rails Admin] and [ActiveAdmin],

following similar approaches in parts, while deviating in others

in order to offer a more simple, common-ground approach

in describing and accomplishing common program use cases.

c4lliope · 2022-11-06T20:40:35Z

A piece of evidence on this would be the section Rails Admin Interfaces at https://www.ruby-toolbox.com/. Administrate is listed there alongside other gems that occupy a similar space, and the word "admin" is common to many of them.

@pablobm; many programmers are no longer using master in describing their main code branches. In a similar regard, admin is based on minister, and our name causes me pain upon seeing such a poorly chosen hokey phrase.

I'm also eager to begin making changes again because I had designed our code as being endlessly pre-1.0; our users recognize some changes could be coming along on the schedule, and so long as someone can easily upgrade (rails generate ...), I see no problems in choosing a more reliable, on-brand name. "Administrate" simply becomes a precursor library, and had helped us learn our user's needs more.

c4lliope · 2022-11-06T20:45:06Z

Perhaps one more reason is the class of so-called "admin" engines is really bounded by prior norms;
our code's real skill is producing loosely-described pages, in a similar manner as low-code website builders.
I'd like a name encouraging us to expand our game and help people encode more complex use cases easily.

pablobm · 2022-11-24T14:32:25Z

docs/permissions.md

+[Pundit] is a popular gem many people describe permissions rules in.
+Administrate's Pundit plugin applies your permissions across your dashboards.
+See the end of this page.


I think that mentioning Pundit from the get go will lead some users to think that it is a requirement.

Or perhaps this could be rephrased to clarify that this is not the case:

Suggested change

[Pundit] is a popular gem many people describe permissions rules in.

Administrate's Pundit plugin applies your permissions across your dashboards.

See the end of this page.

You can write this logic yourself using your preferred tools. Alternatively, Administrate

provides an easy path to integrate with [Pundit], a popular gem for describing permissions.

For more details, read on.

pablobm · 2022-11-24T14:38:08Z

docs/permissions.md

+Permissions can be described in `Admin::ApplicationController`
+or any subclass.
+
+Here are some examples:


I think this doesn't make it clear enough that the examples are indeed the full API that users will need to override in order to implement authorization. How about the following?

Suggested change

Here are some examples:

The following are the methods that you will need to override in order to implement your own permission scheme, shown with example implementations:

pablobm · 2022-11-24T14:42:39Z

docs/specialized_actions.md


-To set the default sorting on the index action you could override `default_sorting_attribute` or `default_sorting_direction` in your dashboard controller like this:
+You can order records on index actions


Ordering can be decided by the user in many cases by clicking the table headers. This piece of advice refers to the default order:

Suggested change

You can order records on index actions

You can set the default order of records on index actions

pablobm · 2022-11-24T14:44:32Z

docs/specialized_dashboards.md

+by adding or dropping member names as symbols in each corresponding array.
+
+Your `ATTRIBUTE_TYPES` hash should describe
+each member's shape, as dispalyed in each dashboard page.


Suggested change

each member's shape, as dispalyed in each dashboard page.

each member's shape, as displayed in each dashboard page.

pablobm · 2022-11-24T14:53:34Z

admin is based on minister, and our name causes me pain upon seeing such a poorly chosen hokey phrase.

I'm curious, what is the issue with the etymology?

c4lliope added 4 commits August 24, 2022 15:15

begin redescribing gem.

e29c43d

Keep redescribing gem, page by page.

1131b36

Rename pages in guide index.

c23fa1b

Again, rephrase and redescribe.

415bc62

pablobm reviewed Oct 20, 2022

View reviewed changes

pablobm reviewed Nov 24, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Redescribed #2255

Redescribed #2255

c4lliope commented Aug 24, 2022 •

edited

Loading

c4lliope commented Aug 25, 2022

pablobm left a comment

pablobm Sep 29, 2022 •

edited

Loading

pablobm Sep 29, 2022

pablobm Sep 29, 2022

pablobm Sep 29, 2022

pablobm Sep 29, 2022

pablobm Sep 29, 2022

pablobm Sep 29, 2022

c4lliope commented Nov 6, 2022 •

edited

Loading

c4lliope commented Nov 6, 2022

pablobm Nov 24, 2022

pablobm Nov 24, 2022

pablobm Nov 24, 2022

pablobm Nov 24, 2022

pablobm commented Nov 24, 2022

	Our engine helps you manage records in your Rails program.
	Manage records in your Rails app.

	[See a copy running online][online].
	[See a demo in action][online].

	### Danger: breaking changes are common.
	### Warning: breaking changes are common.

	and breaking changes can occur as our designs respond
	and breaking changes can occur as our designs evolve

	Make sure you see remarks included in our [release log],
	Make sure you read our [release log],

		super-user dashboards across a broad range
		of program shapes and sizes.

	Here are some examples:
	The following are the methods that you will need to override in order to implement your own permission scheme, shown with example implementations:


		To set the default sorting on the index action you could override `default_sorting_attribute` or `default_sorting_direction` in your dashboard controller like this:
		You can order records on index actions

	You can order records on index actions
	You can set the default order of records on index actions

	each member's shape, as dispalyed in each dashboard page.
	each member's shape, as displayed in each dashboard page.

Redescribed #2255

Are you sure you want to change the base?

Redescribed #2255

Conversation

c4lliope commented Aug 24, 2022 • edited Loading

c4lliope commented Aug 25, 2022

pablobm left a comment

Choose a reason for hiding this comment

pablobm Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

c4lliope commented Nov 6, 2022 • edited Loading

c4lliope commented Nov 6, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pablobm commented Nov 24, 2022

c4lliope commented Aug 24, 2022 •

edited

Loading

pablobm Sep 29, 2022 •

edited

Loading

c4lliope commented Nov 6, 2022 •

edited

Loading