Contrib.social

Phase out OG Guides, everything OG Pages?

Open on Drupal.org →
Created on 5 March 2025, about 2 months ago

Problem/Motivation

The Drupal documentation works well, though there are some pain points, and the relationship between OG Guide vs OG Page is a difficult one for new users.

I know I certainly wasn't sure when to use one or the other in the beginning ... only after trial and error did I understand their relationship somewhat.

Steps to reproduce

Start contributing Drupal documentation, and feel nervous you're doing something wrong, or not sure what to do. Create a Guide? a Page? It's not clear what the difference is ... Also when editing documentation, a new user will notice that sometimes there's a weird limit of a 1000 characters (it's because it's an OG Guide).

Proposed resolution

I am not sure if it's possible, but could OG Guides be converted into OG Pages, as part of the Drupal 10 update? Or maybe the new drupal.org is switching to Group instead (from Organic Groups), or maybe none of them, and will just use Drupal's fine grained permissions?

Alternatively, we could add some text above OG Guides and OG Pages to clarify the difference.

Remaining tasks

Help new users who contribute to Drupal documentation, by either:

  1. Clarify the difference between OG Guides and OG Pages (Easy)

    Making the difference between OG Guides and OG Pages and their relationship clearer, and when to use one or the other, maybe by showing this at the very top, when creating or editing them?

    OG Guide:

    This is a Guide (Organic Groups) with a limit of 1000 characters, which can have Pages (Organic Groups) under it.

    OG Page:

    This is a Page (Organic Groups) with unlimited characters, placed under a Guide (Organic Groups).

  2. Turn OG Guides into OG Pages ... (difficult)

    Guides are used to maintain permissions for a specific Guide:

    New pages and guides *
    Are approved automatically
    Require review and approval to be added to this guide’s menu

    Would dropping this setting for a universal setting "Are approved automatically" allow turning Guides into Pages?

    As a side effect, it would alleviate another Drupal documentation pain point, of new documentation pages not getting added to the menu, where perfectly good new documentation pages linger in limbo for months and years ( #3314821: Add new Menu column and filter to Documentation management page (view) → ).

User interface changes

API changes

Data model changes

✨ Feature request
Status

Active

Version

1.0

Component

Documentation

Created by

🇩🇰Denmark ressa Copenhagen

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

Comments & Activities

  • Issue created by @ressa
  • Comment about 2 months ago →
    🇺🇸United States drumm NY, US

    For the modern version of the site, we are not using OG for this. Instead just a straightforward entity reference to the parent guide, and building customization around that.

    I agree we should consider merging the content types into just documentation pages. There isn’t much practical difference between the two content types. And any amount of planning guide hierarchy upfront will still want guide/page switches as the content evolves over time.

    This is not something we could do in D7, the OG Menu setup is already not scaling well. One menu per page would not be workable.

  • Comment about 2 months ago →
    🇩🇰Denmark ressa Copenhagen

    Thanks for a fast reply, explaining the future plans for the documentation @drumm.

    I do hope the "add to menu" permissions will be relaxed in the new system, so that ordinary users can create, publish and add them to the menu, to prevent new pages to stay semi-hidden. As I see it, weeding out occasional spam in the documentation is a smaller task, compared to the damage of great, new documentation pages in limbo.

    Since there is a plan for a simplification, there's nothing more to do here, so closing.

  • Comment 22 days ago →
    🇩🇰Denmark ressa Copenhagen

    Turn OG abbreviations into something meaningful.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024