Consolidated Support and Documentation Model for GhostBSD

1. Official Channels

2. Channel Responsibilities

Flarum

  • All informal support, help, and discussion goes here

  • Forum categories guide users to post in the right place

  • Topics that prove valuable can be distilled into documentation or tracked as GitHub issues


GitHub

  • Only reproducible bugs and clearly scoped feature requests

  • Use templates to enforce clarity

  • Flarum threads can be referenced if context helps, but GitHub remains lean and focused


ReadTheDocs

  • Only high-quality, curated, versioned content

  • Prominent links back to Flarum for help and GitHub for technical bugs

  • Every doc page can end with:


    > Still have questions? Ask on the forum or open an issue


3. Suggested Flarum Tag Structure

Main Tags:

  • Support

    • Installation
    • Hardware Compatibility
    • Networking and Wi-Fi
    • ZFS and Encryption
    • Boot Environments

  • Tutorials and Guides

    • Desktop Customization
    • Power Management
    • Package Management
    • System Recovery

  • Community and Meta

    • Feature Proposals
    • Site Feedback
    • Contributor Onboarding

4. Interlinking Strategy

  • From Flarum → Docs: Curated and validated answers turn into guides
    • From Docs → Flarum: “Have questions? Ask here” links after each section
    • From GitHub → Docs: Tag issues that require or improve documentation with docs-needed
    • From Flarum → GitHub: Escalate confirmed bugs, tagging with context and link to thread

5. Community Workflow Summary

[User has problem]
        ↓
[Search Docs at ReadTheDocs]
        ↓
[If unanswered → Ask on Flarum]
        ↓
[If verified bug → Maintainer opens GitHub issue]
        ↓
[Fix merged → Docs updated → Flarum thread closed with summary]

    GitHub

    vimanuelt … Only reproducible bugs and clearly scoped feature requests …

    Any number of useful things can be done with https://github.com/orgs/ghostbsd/projects/4/, for the development management project, in ways that can clarify for things for end users (in addition to developers).

    https://github.com/orgs/ghostbsd/projects/4/views/19?filterQuery=&sliceBy%5BcolumnId%5D=58331422&layout=table&visibleFields=%5B%22Title%22%2C%22Status%22%2C%22Labels%22%2C107091%2C4472642%2C58331422%5D was the result of toying for five minutes … just scratching the surface.

      vimanuelt Use templates to enforce clarity

      Don't enforce a templates-only approach. Allow free-form.

          vimanuelt Every doc page can end with:


          > Still have questions? [Ask on the forum](https://forums.ghostbsd.org/) or [open an issue](https://github.com/ghostbsd/issues/issues/new?assignees=&labels=feature&template=feature_request.yaml)

          I'd prefer no clutter.

          The footer should have a simple link to the GhostBSD home page, if possible.

            ericbsd … GhostBSD Dev Telegram. …

            It's fine, for people who enjoy it, however Telegram users should remember that all knowledge there is pretty much useless to the public, if not echoed/duplicated or acted upon outside Telegram – in some public space.

            In a consolidation context: I don't perceive any flow of information.

              Consolidated Support and Documentation Model for GhostBSD (Refined)

              1. Official Channels

              2. Channel Responsibilities

              Forums (Main Entry Point for Users)

              • First-line support and troubleshooting
              • Community guides, onboarding help, hardware questions
              • Threads that demonstrate technical merit can inform docs or GitHub issues

              GitHub

              • For confirmed, reproducible bugs and scoped feature requests
              • Should remain focused, using templates optionally to guide structure
              • GitHub Projects (like Project 4) can help visualize roadmap and triage

              ReadTheDocs

              • Canonical documentation
              • Do not clutter the footer with calls to action: a minimal, clear link to ghostbsd.org is sufficient
              • Contributor-driven updates derived from forum threads or GitHub issue resolution

              3. Suggested Forum Tag Structure (Revised)

              This approach flattens the structure and avoids overcategorization, allowing newer users to find relevant content quickly.

              4. Interlinking Strategy

              • Forum threads that expose systemic issues → turned into GitHub issues
              • GitHub resolutions or feature completions → summarized and linked in forum and docs
              • Forums can include pinned posts linking to documentation and how to file issues
              • Docs link only to homepage, keeping footers decluttered as per Graham’s point

              5. Community Workflow Summary (Realistic)

              User has problem
    ↓
Checks ReadTheDocs or search on forums
    ↓
If unclear, posts question on forums
    ↓
If bug confirmed, developer or moderator creates GitHub issue
    ↓
Fix issued → Summary added in forums → Docs updated if necessary

              6. Handling Telegram and Reddit

              • Telegram should be considered informal, ephemeral and deprecated for technical use

              • Core discussions must be echoed to forums or GitHub to avoid knowledge loss

              • Reddit may continue as outreach and discovery, but every post should include a clear redirect:


                > For support, please visit forums.ghostbsd.org


              Final Notes

              This model:

              • Reduces sprawl
              • Respects Graham’s valid points on clarity and minimalism
              • Keeps forums user-friendly and visible
              • Uses GitHub for structured dev work and long-term issue management
              • Leaves ReadTheDocs clean and non-intrusive

                That is okay. The documentation, not the forum, should be the golden source of truth.

                We do not want to duplicate the problems other projects have by having multiple sources of competing truths.

                grahamperrin
                The forums can be considered a working space. The documentation (ReadTheDocs) can be considered a filing cabinet. The project just needs one person assigned to add to the filing cabinet. Perhaps Rodney would like to volunteer and Eric would be the documentation manager.

                We can bypass the shortcomings of the forums by using ReadTheDocs as the golden source of truth. It would be good to manage truth in one location instead of several. Search engines and LLMs can have access to the golden source of truth.

                  This is an important lesson drawn from observing FreeBSD. Relying on forums and mailing lists as informal archives results in fragmented knowledge, duplicated effort, and confusion for new users. We should avoid repeating this mistake.

                  The forum should function as a space for active discussion, collaborative problem-solving, and informal support. It should not be treated as a permanent source of truth. Using a forum in that way is comparable to relying on an email inbox as a documentation system. It is inherently disorganized, impermanent, and difficult to search reliably. Ideally, forum content should be considered ephemeral, with older threads being archived or expired after a defined period, such as ninety days.

                  The core issue remains the limited scope and depth of the official documentation on ReadTheDocs. Until the documentation is comprehensive and regularly updated, users will continue turning to the forum for definitive answers. This leads to inconsistent and often conflicting guidance.

                  The correct approach is to treat the documentation as the primary reference. When consensus or verified solutions emerge through discussion, they should be written into the official documentation. That documentation must be concise, versioned, and aligned with the actual system behavior. It should evolve as the project evolves. This ensures that users have a consistent, trustworthy foundation rather than a scattered collection of forum posts.

                    Distilling truth is not the role of search. Search helps locate content, but it does not evaluate its accuracy or relevance. The responsibility for delivering reliable information lies with managed documentation. The goal is to save the user time by providing accurate, vetted, and clearly organized guidance. Well-maintained documentation eliminates the need to sift through conflicting opinions or outdated posts, allowing users to focus on understanding and applying correct information efficiently.

                    grahamperrin ability to flag one's own content.

                    I can not.

                    vimanuelt … The forum should function as a space for active discussion, …

                    When I feel hindered, I don't feel active.

                    vimanuelt … Ideally, forum content should be considered ephemeral, with older threads being archived or expired after a defined period, such as ninety days. …

                    I understand the wish, however it's not ideal.

                          vimanuelt Reddit may continue as outreach and discovery, but every post should include a clear redirect:


                          > For support, please visit [forums.ghostbsd.org](https://forums.ghostbsd.org/)

                          A firm "no" to repetitive clutter.

                          Eric's plea is already suitably prominent at the front page:

                          {Screenshot: the new Reddit view of /r/GhostBSD}

                            vimanuelt It would be nice if the FreeBSD community could do something similar.

                            For documentation, there have been various discussions about consolidation and the like. freebsd-doc exists, mostly automated email from Bugzilla (I don't expect to find summaries of discussions there, or in official status reports – sorry).

                              This is why minimising the number of communication channels is so important. When discussions are scattered and difficult to track, valuable and time-sensitive information is more likely to be lost or overlooked. It brings me back to the proposal for a consolidated support and documentation proposal and the following proposal:

                              Proposal: Documentation Policy and Use of the Flarum Forum

                              Background
                              The GhostBSD community currently utilises the Flarum forum for discussion and support. While this platform is valuable for interactive dialogue, it is not an ideal medium for maintaining long-term, structured documentation.

                              Proposal

                              1. Restrict the Scope of Flarum
                                The Flarum forum should remain private or unindexed by design. Its purpose should be limited to user discussion, troubleshooting, coordination, and idea sharing. It should not be used to host persistent, reference-style content.

                              2. Centralise Documentation on ReadTheDocs
                                The GhostBSD ReadTheDocs site should be regarded as the authoritative source for all structured and long-term documentation. This platform supports proper formatting, version control, collaborative editing, and reliable indexing by search engines—ensuring that users can locate accurate and up-to-date information efficiently.

                              3. Search Engine Visibility
                                Flarum’s limited indexing by search engines is a benefit. It prevents informal, outdated, or speculative forum discussions from appearing ahead of verified documentation in search results. This improves signal-to-noise ratio and directs users to curated, official guidance.

                              4. Browser Compatibility
                                As an additional practical note, ReadTheDocs works reliably with Gecko-based browsers, such as Firefox and Waterfox, which may not always render other documentation formats or platforms consistently.


                              Conclusion
                              This policy encourages clarity, reduces user confusion, and strengthens the documentation workflow. By clearly delineating the roles of forum and documentation platforms, we can improve onboarding, support, and long-term maintainability of GhostBSD's knowledge base.

                              Here is a script for pruning the Forums: https://forums.ghostbsd.org/d/352-flarum-prune-old-postssh

                              How This Script Improves the Forum

                              1. Keeps Content Fresh and Relevant
                                Old discussions that are no longer useful or accurate are automatically removed, ensuring that users engage with up-to-date information.

                              2. Reduces Cognitive Load for Users
                                By trimming stale threads, users can more easily focus on current and unresolved topics without sifting through legacy clutter.

                              3. Improves Signal-to-Noise Ratio
                                Outdated or unanswered posts are purged, making the forum’s search results and tag listings more concise and informative.

                              4. Encourages Documentation Flow
                                Important findings are encouraged to be formalised in maintained documentation (e.g., ReadTheDocs), instead of buried in ephemeral forum discussions.

                              5. Enhances Performance and Maintainability
                                A leaner database with fewer obsolete entries results in marginally better performance, faster backups, and easier moderation.

                              6. Establishes Lifecycle Discipline
                                Reinforces that the forum is for short-term discourse and support, not for indefinitely storing conversations, leading to clearer content governance.

                              7. Reduces Political Advocacy Risks
                                Automatically removing legacy content limits the lifespan of posts that may contain off-topic ideological discussions, political statements, or advocacy. This helps maintain the forum’s focus on technical and collaborative content, discouraging forum misuse as a platform for agenda-driven messaging.

                              8. Discourages Forum-as-Soapbox Mentality
                                The transient nature of content encourages brevity, relevance, and technical focus, reducing incentives for users to post long-form personal or political commentary that detracts from the project’s purpose.

                                vimanuelt

                                IIRC Google made a huge mistake, many years ago, with Google Groups: topics were automatically locked after six months.

                                This caused terrible problems for multiple open source projects that used the service.

                                Removing content would be even worse. A firm "no" to pruning GhostBSD Forums.

                                    grahamperrin
                                    Pruning may become necessary if performance degradation continues. I am already encountering issues when posting. Scaling the infrastructure, whether vertically or horizontally, would incur additional costs. In contrast, pruning provides a low-impact, cost-effective way to maintain responsiveness and reduce system load.