>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3623551. --> Reported by: [ivrh](https://www.drupal.org/user/149520) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Entity Activity project page currently contains most of the user documentation. It is difficult to scan, duplicates the repository README, and still omits important setup steps that are only discoverable from the module UI and source code.</p> <p>The information must be moved, not simply deleted. Existing guidance should be retained when it remains accurate, corrected where implementation details have changed, and explicitly retired when it is obsolete.</p> <p><a href="https://git.drupalcode.org/project/entity_activity/-/merge_requests/5">Merge request !5</a>, opened in November 2022, only converts the then-current README.txt headings to Markdown. It does not modernise or verify the content and predates later 1.x changes, so it should not be merged unchanged.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ol> <li>Inventory every section of the project page, README.txt, and the Entity Activity Mail README.</li> <li>Verify the documentation against the 8.x-1.x routes, forms, plugins, permissions, default Views, templates, cron queues, tests, and submodules. Use 1.x as the implementation baseline for this task.</li> <li>Create a Drupal.org guide with separate pages for overview and quick start, core configuration, displaying and managing activity, Entity Activity Mail, Mass Subscribe, extending and theming, and troubleshooting/FAQ.</li> <li>Shorten the project page to the information needed to evaluate the module: summary, features, requirements, post-installation overview, similar projects, and links to the detailed guide.</li> <li>Add the guide to the project page Resources &rarr; Documentation field.</li> <li>Replace README.txt with a current README.md entry point on 8.x-1.x. Preserve useful package-level information and link to the canonical Drupal.org guide. Incorporate any still-relevant formatting work from merge request !5 rather than merging that stale branch unchanged.</li> </ol> <h3 id="summary-reverse-engineered-gaps">Documentation gaps found</h3> <ul> <li>The required order of enabling subscribable entity types, placing the Subscribe on display component or block, assigning permissions, creating a generator, and enabling it.</li> <li>Generator options for operations, bundles, published entities, direct or referenced subscriptions, parent taxonomy terms, tokenised messages, and immediate or cron-based generation.</li> <li>Log retention by age or per-user limit, including the performance implications of purge and per-user-language generation.</li> <li>Provided administration and per-user Views, read/unread and removal components, subscriber local tasks, blocks, and exact permissions.</li> <li>Mail enablement, default user frequency, cron/queue behaviour, report filters, read-state handling, translated settings, mail fields, and theming.</li> <li>Mass Subscribe methods, permissions, and unsubscribe mode.</li> <li>Extension points, custom log-generator plugins, supported-entity-type event, entity lifecycle events, fields, templates, and view-mode override.</li> </ul> <h3 id="summary-information-preservation">Information preservation</h3> <p>Requirements, installation, similar modules, generator configuration, displays, multilingual behaviour, permissions, provided widgets, subscriber lists, Mail, Mass Subscribe, theming, FAQ, maintainers, and sponsorship must each be mapped to the new project page, guide, or README before the old long description is replaced.</p> <p>The obsolete Drupal 8 installation link and the unsupported Swift Mailer recommendation should be replaced with current, version-neutral guidance while preserving the underlying installation and HTML-mail requirements.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ol> <li>Create and review the documentation guide and child pages.</li> <li>Update the project page and Documentation resource link.</li> <li>Prepare the README.md change for 8.x-1.x. Updating the 2.x README is explicitly out of scope and will be handled separately.</li> <li>Verify all links and compare the final documentation inventory with the existing page and README files.</li> </ol> <h3 id="summary-acceptance-criteria">Acceptance criteria</h3> <ol> <li>The published guide documents an end-to-end setup that a site builder can follow without reading source code.</li> <li>Every substantive section of the current project page and README files is retained in an appropriate location or recorded as obsolete with a reason.</li> <li>The project page remains concise while retaining requirements, key features, similar-project guidance, and a clear documentation link.</li> <li>The guide accurately covers the current behaviour verified from 8.x-1.x and does not claim unverified version-specific behaviour.</li> <li>README.md on 8.x-1.x follows the current Drupal template and points to the canonical guide.</li> <li>Configuration paths, permissions, supplied UI components, cron behaviour, and submodule workflows are verified against implementation or tests.</li> </ol> <h3 id="summary-ui-changes">User interface changes</h3> <p>Documentation-only. The Drupal.org project page and documentation navigation will change.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p>