Proposal for a Consolidated Support and Documentation Model

vimanuelt

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

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.
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.
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.
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.

vimanuelt

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

How This Script Improves the Forum

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.
Reduces Cognitive Load for Users
By trimming stale threads, users can more easily focus on current and unresolved topics without sifting through legacy clutter.
Improves Signal-to-Noise Ratio
Outdated or unanswered posts are purged, making the forum’s search results and tag listings more concise and informative.
Encourages Documentation Flow
Important findings are encouraged to be formalised in maintained documentation (e.g., ReadTheDocs), instead of buried in ephemeral forum discussions.
Enhances Performance and Maintainability
A leaner database with fewer obsolete entries results in marginally better performance, faster backups, and easier moderation.
Establishes Lifecycle Discipline
Reinforces that the forum is for short-term discourse and support, not for indefinitely storing conversations, leading to clearer content governance.
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.
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.

grahamperrin

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.

vimanuelt

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.

Robin

I think people are looking for "plain and simple language" when they do a topical search. If the only available solutions found are written in technobabble, they're simply incomprehensible. You said yourself that the Forums are the place for plain language discussions that, if they reveal a flaw that requires a super-duper-iltra-mega geeky technobabble solution, then the Docs might be the place for that. I'm with @grahamperrin on this one.

vimanuelt

Robin
I believe you raise an important point regarding the role and structure of documentation. It may be necessary to establish clearer distinctions by introducing dedicated categories such as a User's Manual a Developer's Manual general Documentation and formal Manuals. This separation would help to clarify the intended audience of each resource and ensure that information is presented with appropriate depth and context.

The most effective form of documentation is the one rendered unnecessary because the software is so intuitively designed that no user feels compelled to ask how it ought to be used.

grahamperrin

Robin … plain language discussions …

It's not yet possible to post in an area that might be suitable for discussions that are less plain (more technical).

https://forums.ghostbsd.org/d/53/9

vimanuelt

Robin
The usefulness of a response often depends on the reader’s intent. Some are looking to deepen their understanding of the operating system, while others may simply need material for a blog post or quick reference.

I tend to write with completeness in mind, and I often provide scripts not just as solutions but as examples others can study and learn from. My aim is to help those who wish to grow their understanding, even if the level of detail may not be necessary for every reader.

ericbsd

grahamperrin Issues templates should always be used to ensure quality issue reporting. That said templates can be improved.

vimanuelt

We might consider this thread as being dead. There is no interest in the proposal. :-)

ericbsd

I am just starting to read this. I am not done yet.

grahamperrin

Thanks.

ghostbsd/issues265 is an example of an issue that might not benefit from a template.

ericbsd

A template should be added for website or link issues.

ericbsd

I have been thinking about whether we should have the Contributors' documentation on a GitHub Wiki, although it might be more complex to push changes to a wiki.

grahamperrin

ericbsd are pull requests possible?

From what I have seen (including content that's FreeBSD-oriented), GitHub wikis are no more likely to be maintained than other wikis.

vimanuelt

It would be helpful to have a single tool for managing all documentation workflows. For example:

ghostbsd-doc -web to update the website
ghostbsd-doc -wiki to maintain the wiki
ghostbsd-doc -rtd to publish to Read the Docs

Consolidating these tasks into one command-line utility would simplify documentation management and reduce duplication of effort.

ericbsd

vimanuelt wiki, most go, it might be a disaster waiting to happen. I do not log it to that. It is old and not up-to-date.

The website is on Drupal, so updating it is probably better than updating it manually.

vimanuelt

It was just an idea. :-)

ericbsd

If the website were static, that would be a nice tool to do.

ericbsd

grahamperrin I only referred to the contributors' docs. But keeping it with ghsotbsd/documentation is probably better.

vimanuelt

Wikis are still alive, but the classic open-edit wiki model has declined outside of specific use cases. Static documentation sites and structured knowledge bases have largely overtaken them for professional and polished documentation.

ericbsd

vimanuelt That is true.

« Previous Page