search

totten / civix

CiviCRM Extension Builder
http://civicrm.org/
Other
56 stars 56 forks source link

Readme - Remove clutter #316

Closed colemanw closed 9 months ago

colemanw commented 9 months ago

Removes a bunch of boilerplate that clutters up every extension's readme file.

See https://chat.civicrm.org/civicrm/pl/5z13tkz8o7bypxrp8cis4xec7e

I think the aspiration of this boilerplate is good, but in practice:

artfulrobot commented 9 months ago

Maybe link to https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/ ?

colemanw commented 9 months ago

@artfulrobot thanks, added.

aydun commented 9 months ago

That's all good except that the docs page doesn't include the detailed information for cv dl or git clone Would be helpful not to loose that.

artfulrobot commented 9 months ago

Yeah I think that page could do with an update, but updating one place makes more sense than updating (or rather, not updating) hundreds of extensions.

artfulrobot commented 9 months ago

@coleman looks good to me, thanks.

totten commented 9 months ago

Deja vu: #166

tldr: To replace with these with better docs, we actually need the better docs...

(@colemanw) Installation instructions can be centralized and don't need to be copied into every extension's readme file...

(@artfulrobot) updating one place makes more sense than updating [than many]...

Completely agree. A centralized document can ultimately be better (more thorough/more complete/more thoughtfully edited).

The catch is that nobody on this thread (or the MM thread) has actually updated the docs... or even suggested that they would update them. That was where #166 fizzled out, too.

Perhaps the reason why no one has updated the generic docs is... it's a little fiddly. The commands are simple... if you know a couple variables. But you have to know the variables and plug them in. Depending on goals, you're looking at some subset of these questions:

So, actually, documenting this stuff is not as simple as waiving a hand (idiom).

As I see it, the options are:

  1. (Status quo; cheapest) The default README includes a boilerplate example. When the author publishes the extension, they spend 60 seconds tweaking the README (to fill-in a real URL or fill-in their bespoke instructions).
  2. The README links to generic documentation. Somebody actually works on that. (If an ext needs bespoke instructions, the author adds them on their own.)

  3. The README links to dynamic documentation. Somebody actually works on that. (If an ext needs bespoke instructions, the author adds them on their own.)

    For example, the README might link to a URL like:

    https://download.civicrm.org/ext/MY_KEY?repo=MY_GIT

    The page shows dynamic instructions with a few widgets, and it fills-in some fiddly bits.

    In the interests of pushing forward, here's an example of dynamic instructions: https://jsfiddle.net/kdh6wrxp/1/ But that's only a start.

I do think (2) and (3) are better than (1) -- they'll ultimately produce more informative+maintainable instructions.

What I can't determine is the subtext. Are you (@colemanw or @artfulrobot) implying a real intent to update the docs yourself? Or are you soliciting for someone else (like me) to do the main work? (Not a trick question...)

artfulrobot commented 9 months ago

Here you go: rewrite of extensions page: https://lab.civicrm.org/documentation/docs/sysadmin/-/merge_requests/375

colemanw commented 9 months ago

@totten let's merge this!

totten commented 9 months ago

civibot, test this please

colemanw commented 9 months ago

civibot, test this please

totten commented 9 months ago

civibot, test this please

totten commented 9 months ago

There was an early test fail that was relevant, but I think that the latest one is just HTTPD flakiness.