Contrib.social

Faulty documentation

Open on Drupal.org →
Created on 24 June 2024, 9 months ago

The current documentation is clearly inadequate. It has not been updated for four years.

I wish I could update it on https://git.drupalcode.org, but I'm not allowed to neither edit nor fork over there.

So here's an error ridden, but hopefully useful, stab at some better documentation:

1. The Flysystem module page links to
http://cgit.drupalcode.org/flysystem/plain/README.md?h=8.x-1.x
This page look pretty ugly in a browser. Link to
https://git.drupalcode.org/project/flysystem/-/blob/2.0.x/README.md?ref_...
or some such instead.

Better yet. Include most of the documentation (100+ lines?) on the module page. It's a great place for documentation! People will probably be more likely to install it, if they get the full picture up front.

2. "Reducing technical debt and risk of vendor lock-in." is slightly better than the current "Reducing technical debt and chance of vendor lock-in."

3. Requirements and Installation boilerplate should be removed. This is definitely not the first module a novice Drupal user will choose to install. Spend your time on the important details.

4. "Stream wrappers are configured in settings.php (usually found in /sites/default/settings.php or /web/sites/default/settings.php".
There are two settings.php in a typical D10 installation (the other one is at /core/lib/Drupal/Core/Site). And nearly 20 *settings.php files. We'd hate to confuse people.

5. Troubleshooting. Fine. But place it after the Configuration bit, where people need it.

6. Configuration. The example does not work.

This example will work

$schemes = [
  'local-example' => [ // The name of the stream wrapper.

    'driver' => 'local', // The plugin key.

    'config' => [
      'root' => '/../../', // Path to directory outside Drupal. Maybe /var/www/html/storage or ../ works better, who knows? 'sites/default/files/flysystem' would be a part of the public file system.
      'public' => TRUE, // In order for the public setting to work,
      // the path must be relative to the root
      // of the Drupal install.

      // Optional settings that apply to all adapters.

      'name' => 'local-example', // Optional. Defaults to something secret.
      'description' => 'An example of a local flyssystem file system',  // // Optional. Defaults to something secret.

      'cache' => TRUE, // Cache filesystem metadata. Not necessary for
      // the local driver.

      'replicate' => 'ftp-example', // 'replicate' writes to both filesystems, but
      // reads from this one. Functions as a backup.

      'serve_js' => TRUE, // Serve Javascript or CSS via this stream wrapper.
      'serve_css' => TRUE, // This is useful for adapters that function as
      // CDNs like the S3 adapter.
    ],
  ],

    'ftp-example' => [
      'driver' => 'ftp',
      'config' => [
        'host' => 'ftp.storaro.it', // or whatever the name of your ftp host is
        'username' => 'storaro', // use a better username
        'password' => 'cin3matograph3r', // use a better password

        // Optional config settings.
        'port' => 21,
        'root' => '/var/www/html/storage',
        'passive' => true,
        'ssl' => false,
        'timeout' => 90,
        'permPrivate' => 0700,
        'permPublic' => 0700,
        'transferMode' => FTP_BINARY,
      ],
    ],
];

// Don't forget this!
$settings['flysystem'] = $schemes;

6) Troubleshooting. Have a look at the status report (admin/reports/status) to see if it works.
And on the status page, you should never write "ftp returned an error". That's close to useless. What error did it return? Should the user have a closer look at the hostname, port, username or password?

7) How to use the module.
"Now whenever you add a NEW file field to a node type/entiity type, you can decide which file system to use for the field. You cannot change the file system for existing fields, though. Only new fields get the benefit of the Flysystem module."

🐛 Bug report
Status

Active

Version

2.2

Component

Documentation

Created by

🇩🇰Denmark Steven Snedker

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @Steven Snedker
  • Comment 9 months ago →
    🇺🇸United States lhridley

    The documentation does need some love. Happy to accept a patch for improvements if you would like to submit one, otherwise this is noted and it will go into the backlog.

    Just an observation, you get more flies with honey than with vinegar. Just saying.

  • Comment 9 months ago →
    🇺🇸United States lhridley

    Reclassing as a task, this is not a bug, the module works correctly when it's configured correctly. Documentation updates are not bugs.

  • Comment 9 months ago →
    🇺🇸United States lhridley
  • Comment 9 months ago →
    🇺🇸United States lhridley
  • Comment 9 months ago →
    🇺🇸United States lhridley
  • Comment 9 months ago →
    🇩🇰Denmark Steven Snedker

    I'd love to write a patch, but as you can see I'm not sufficiently fluent in English, I have no useful git.drupalcode.org access and I can't even target the correct version of the splendid Flysystem module. Also I have only an hours experience with the module.

    Looking at the flysystem 2.2.x-dev DEV readme I can see I would have missed quite a few important points. I'd say people were better off if the Flysystem module page linked to the flysystem 2.2.x-dev DEV readme instead of the faulty/less stellar 8.x-1.x readme.

    I'm also happy that useful documentation is now a task and not a bug.

    I was misled by this ChatGPT answer:

    Is faulty documentation of a Drupal module a bug?

    Yes, faulty documentation of a Drupal module can be considered a bug. Documentation is an integral part of software development, as it helps users understand how to use the module correctly. If the documentation is incorrect, incomplete, or misleading, it can cause users to misuse the module or struggle to implement it effectively. This can be as disruptive as a functional bug in the code itself. Therefore, reporting and addressing documentation issues is crucial for maintaining the overall quality and usability of the module.

    Thank you for improving he Flysystem module - and the documentation!

  • Comment about 2 months ago →
    🇺🇸United States lhridley

    @steven-snedker The project page has been updated to link to the current version's README file, and documentation has been cleaned up a bit.

    I'm happy to take any constructive criticism on the documentation if you'd like to provide replacement text for the current README, I can generate a patch and update it, providing credit for the updates to you.

  • Status changed to Postponed: needs info about 2 months ago
  • Comment about 2 months ago →
    🇺🇸United States lhridley
  • Comment about 2 months ago →
    🇩🇰Denmark Steven Snedker

    First constructive comments:

    I suggested

    Include most of the documentation (100+ lines?) on the module page. It's a great place for documentation! People will probably be more likely to install it, if they get the full picture up front.

    Are you going to do that when the documentation is improved?

    2. Did you consider talking about risk instead of chance?
    ChatGPT did!

    I prefer:
    "Reducing technical debt and risk of vendor lock-in."

    The word "risk" aligns better with "vendor lock-in," as it conveys the potential for a negative outcome more clearly than "chance," which can sound neutral or even positive.

    I think ChatGPT is right here. What do you think?

    I know it's a very small and not terribly significant bit of the documentation. But improving the documentation (and learning a bit doing it) is way faster than arguing about the need to improve it. It's also preferable to not improving it.

    3. I still think

    Requirements and Installation boilerplate should be removed. This is definitely not the first module a novice Drupal user will choose to install. Spend your time on the important details.

    This time I might even venture that the boilerplate does more harm than good.

    What do you think?

    4. I still think you should be specific as to which settings.php file the users should seek out. What do you think?

    As for the Configuration bit:

    For example: 'local-example://filename.txt'.

    should not be partially clickable.

    The 'driver' key, is the type of adapter
    'driver' => 'local', // The plugin key.

    Driver, adapter, plugin. It's getting confusing. Too many different words.

    These days I just think the main module should give up providing a useful, working example.

    Farm the job out to the people who can, and link to them.

    You'll save quite a bit of work and the users will save quite some time and frustration.

    Suggestion for the Configuration bit:

    Flysystem will not work unless you add arrays to your settings.php file (usually found at /sites/default/settings.php)

The maintainers of the flysystem submodules will tell exactly what they should look like.

Have a look at [insert the list of submodules/adapters]

    These are currently the best and most useful examples
    https://www.drupal.org/project/flysystem_dropbox →
    https://www.drupal.org/project/flysystem_gcs →
    https://www.drupal.org/project/flysystem_aliyun_oss →

    Why? You'll spot the examples immediately, and they work.

    Spend some time telling the maintainers of the submodules to
    a) upgrade to D11 and
    b) provide examples starting with
    $settings['flysystem'][s3'] = ...
    $settings['flysystem']['dropbox'] = ...
    $settings['flysystem']['cloud-storage'] = ...
    ...

    (because $schemes = ... ; $settings['flysystem'] = $schemes; is not adequately copy&paste friendly).

    c) Turn the adapters local and ftp into submodules like the ones above.

    Then it'll be way easier to install Flysystem and her submodules.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024