Contrib.social

Improve the documentation

Open on Drupal.org →
Created on 19 February 2023, over 1 year ago
Updated 22 February 2024, 4 months ago

Problem/Motivation

We need good documentation for different audiences/levels: overview + evaluation; site admin; developer; etc.

Proposed resolution

We can use this issue to sketch out the intended structure. For each page/topic we can define the audience, topic, etc. The maintainer/developer needs to focus on writing code and anyway is not the best technical writer😃. However we need to ensure the documentation is technically accurate so the maintainer should review.

Practical

  • When we are creating new pages, it's OK to write without so much planning. The pages can be marked as draft, and it's fine for them to stay a while without review.
  • When editing existing live pages then people will be reading them, so we need to take care not to introduce errors. We should have a clear agreed plan before starting changes. Or we could take a copy, and edit the new draft somewhere else.
  • The Drupal documentation system can be a pain - I found pages slow to load, the editor buggy, and the system inflexible (easy to get conflicts, hard to make large changes to the structure). We could write and review new pages somewhere else then copy them in when finished.

Specific cases

There are some specific cases, for example "migration from swiftmailer".

@AdamPS said: Most of the documentation should be general, so that it applies to all readers. We should keep specific cases separate in their own sections.
@nofue said: I think the whole workflow should be in focus when actually offering a step by step recipe.

Both are good point, so here is my suggestion:
Make the "migration from swiftmailer" page into a standalone recipe, instead of referring back to "getting started". However it should be brief and to the point, not duplicating all the general explanation on the other page.
The getting started → page should be general, with only the first sentence linking to the swiftmailer page - and we can cut the words "before you begin".

Remaining tasks

📌 Task
Status

Active

Version

1.0

Component

Documentation

Created by

🇬🇧United Kingdom AdamPS

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

Comments & Activities

  • Issue created by @AdamPS
  • Comment over 1 year ago →
    🇦🇹Austria nofue

    Much nicer space here, so airy :) OK, as I said in my emails, I have yet to get a working structure for this (and probably other) documentation. For starters I'm going to publish a first draft of the intended structure, maybe already today.

  • Comment over 1 year ago →
    🇦🇹Austria nofue
  • Comment over 1 year ago →
    🇬🇧United Kingdom AdamPS

    Great thanks. I added some ideas into the IS.

  • First commit to issue fork.
  • Comment 11 months ago →
    🇺🇸United States ExTexan

    A huge +1 on this. It is desperately needed.

    So far, my colleague and I have spent almost 20 hours trying, without success, to get SymfonyMailer working in a Drupal 9.5 site. With limited documentation, and misleading/contradictory/outdated posts from Google searches, to guide us, we've had to resort to trial-and-error, best guesses, and looking through module code - all to no avail.

    Please make sure that the documentation shows actual code examples on how to accomplish each of the three "levels" of integration (from this page → ).

    Also, may I add... as I said, this is desperately needed, so the first draft doesn't need to be all that pretty; the structure/format can be cleaned up later. I'd be happy for a simple page with somewhat detailed explanations, and the all-important code examples ASAP.

  • Comment 11 months ago →
    🇬🇧United Kingdom AdamPS

    We all agree that it is needed. This is open source code that anyone can use for free. As the developer, I am giving lots of time for free to write this code. That's good news for everyone because swiftmailer is unsupported. Over 10000 Drupal sites are now using the module and probably quite a few of them are profitable. Probably many of the people posting issues here are getting paid to do it, but I'm not getting paid to respond.

    When someone says "please make sure that ..." or "I'd be happy for ...", even adding "ASAP" I wonder who they are talking to😃. So far not a single one of these websites/developers making money from this module has offered to support the development or documentation. That's fine because I'm not doing it for the money, but let's be clear that I'll spend my free time how I choose😃.

  • Comment 11 months ago →
    🇺🇸United States ExTexan

    Point taken. My apologies. My post was written after the aforementioned 20 hours of effort - I shouldn't have let my frustrations creep into my post.

  • Comment 4 months ago →
    🇺🇸United States kenrbnsn New Jersey

    Good documentation is sorely needed.

    I am trying this module for the first time since it looks like it makes sending emails from my custom module very simple. I am not converting from Swiftmail, so I have no knowledge of that module.

    Currently, I'm stuck at trying sending HTML email messages. Googling, I see references to the function setHtmlBody, but when I try to use that, I get a WSOD with this error:

    LogicException: setHtmlBody function is only valid in phases 3-3, called in 1. in Drupal\symfony_mailer\Email->valid() (line 595 of modules/contrib/symfony_mailer/src/Email.php).
    Drupal\symfony_mailer\Email->setHtmlBody('Please ignore this email.State:KS') (Line: 144)

    There should be a simple example given that does this type of function.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024