My experience with FreeBSD handbook have brought some thoughts/ideas:

  1. Documentation should be more Unix-like, do/explain one thing, and do it well (proper documentation should be build from these reusable snippets)
  2. Those snippets should be tagged - for which OS version it is, for which architecture, etc. so that unneeded snippets could be filtered out
  3. They should be connected with code they document, so that when code is changing they will be automatically flagged for revision.
  4. They could be categorized by AI

    Current documentation – defaults to latest:

    https://ghostbsd-documentation-portal.readthedocs.io/

    The Upstream Documentation caption (section) is ideal for users seeking help with MATE or FreeBSD. The absence of a link to Frequently Asked Questions for FreeBSD is good. When upstream takes care of most things, there should be not too much to document for GhostBSD.

    GhostBSD Frequently Asked Questions should be expanded, minimally – don't make the page too long. Add links out to pages for:

    Whatever's done, remember the KISS principle. The invitation to edit on GitHub is ideal.

      grahamperrin I agree, that's why documentation should be usable without tags. But tags should help with filtering out unneeded informations. For example, graphics card chapter without filtering could contain these:

      1. Amd
      2. Intel
      3. Nvidia
      4. Hybrid tips

      with filtering, it could contain just the info for a user GPU and general info, true for all GPUs. Tags should also be "inteligent", if there are two GPU tags, it should also contain the "Hybrid tips". It is more important to be able to filter out unneeded information, than find just the info for the specific GPU (it can be done with any search engine). And with small documentation snippets it's easier to verify/update informations.
      As for troubleshooting tag, it is not a good tag, it is so general, that it is quite useless. And troubleshooting is the art of filtering out unneeded informations 😉
      As for issues with FreBSD, I have some thoughts:
      Repos should be made for released versions, not "quarterly", and published when all packages are ready (Release shouldn't be published when all packages aren't ready). It's practically impossible with "Quarterly" release. There's always question, when one can switch to it? It's moving target, and moving targets are very hard to document properly.
      Documentation is good, but no need for documentation is better. It means that system should behave predictably. For example, if there's GPU driver package in the default repo, it should work after installation, user shouldn't be forced to look why it doesn't work, how to make it work or to think when it will start to work. If there's no way to repair it, document it properly. Because it is documentation that makes a difference between bug and a feature.

          9 days later

          Astropi brings up thoughtful ideas, and I'd like to echo a few and raise some questions.

          1. Modular Docs with Tags
          Could documentation be made more modular, with short, focused snippets tagged by OS version, architecture, and hardware, such as gpu, intel, or 13.2? Tags wouldn’t need to be required but might help users filter for relevance. Would it be feasible to use lightweight metadata or a sidebar filter on ReadTheDocs?

          2. Release and Package Readiness
          Might it help if releases were announced only after key packages, like GPU drivers or Wi-Fi firmware, are confirmed working? The “quarterly” model can make it hard to know when a release is truly ready for general use. Could experimental packages be flagged more clearly in the repo?

          3. Predictability Over Documentation
          Would it be reasonable to aim for packages in the default repo to work out of the box? When they don’t, could clear notes or warnings help users know what to expect? Maybe GhostBSD could define a baseline for supported hardware where full functionality is expected, including sound, suspend, and networking.

          4. Feedback Loop from Forums to Docs
          Could we tag recurring support threads as docs-needed and encourage users or contributors to turn those into draft documentation? That way, real issues seen in the community could directly inform the official docs.

          Would there be interest in trying a tag-based doc format or a checklist for future releases?

          Number 3 I find already in Software Station, but knowing ahead of time is better still.

          A hardware compatibility page, linked from the Homepage which would show what hardware runs GhostBSD well without modifications or extra drivers and/or scripts to install and use.

          Something that works well for the MX-Linux project is what they call a QSI (quick system info). It's just a script that creates a cursory hardware and software profile with output designed to be shared in their forums when making support requests. A glance at that QSI in the forums enables helpers to quickly identify issues.

            It's no longer necessary to specify /views/3

            3 is now the default, in response to https://github.com/orgs/FreeBSDFoundation/projects/1.

            Related: Laptop Support and Usability (LSU) improvements: project workflow changes – May 2025

            From Reddit:

            Where the update refers to https://github.com/FreeBSDFoundation/proj-laptop/blob/main/monthly-updates/Q1-2025-roadmap.pdf, here's a cleaner view of the PDF (without the GitHub framing):

            (Mozilla Firefox loads the PDF without difficulty. Microsoft Edge and www/chromium 134.0.6998.165_1 might be less streamlined.)

                grahamperrin
                Yes, and I sincerely wish them well in their endeavours. However, let us hope these new efforts deliver a meaningful return on investment. If history is any indication, the outcomes are frequently marginal.

                Over the years, initiatives led by the FreeBSD Core Team and funded by the FreeBSD Foundation have often begun with considerable enthusiasm, yet many have failed to achieve lasting impact. Repeated attempts to modernise the FreeBSD documentation portal, for example, have resulted in fragmented and inconsistently maintained resources, despite multiple redesigns.

                Although the Foundation has supported commendable technical work, including enhancements to the toolchain, security audits, and improvements aimed at cloud readiness, many of these projects have not translated into broad adoption or visible progress. For instance, the Foundation funded a security audit of the bhyve hypervisor and the Capsicum framework, reflecting a commitment to proactive security measures. However, the broader impact of these audits on adoption and community engagement remains limited.

                The underlying issue is not a lack of skill or intention, but rather a persistent pattern. There is insufficient coordination with the wider community, an absence of clearly defined success metrics, and a tendency to prioritise foundational infrastructure over improvements that directly benefit end users. Unless these structural challenges are addressed, the return on investment is unlikely to improve significantly.

                The most valuable lessons are often those gained by observing the mistakes of others. When they do succeed in delivering as promised, we should not hesitate to acknowledge and celebrate their achievements.

                  As you can see, I am not satisfied with the current state of FreeBSD’s documentation. Meaningful improvements would be most welcome, not only for FreeBSD itself but also because such progress would directly benefit derivative projects such as GhostBSD. I sincerely hope that GhostBSD’s documentation efforts do not fall prey to the same shortcomings. It is both timely and worthwhile to discuss how best to avoid such pitfalls and establish a more robust, maintainable documentation model.

                  Suggestions are most welcome. It is always enlightening to hear a range of perspectives. Let the best ideas prevail. This is not intended as a contest of wills, but rather a constructive exchange in pursuit of progress. :-)