Technical discussion

grahamperrin

vimanuelt … we should adopt a more sustainable approach: use GitHub issues and the GhostBSD-Dev Telegram group for all technical discussions. GitHub offers structured threads, searchable history, and improved visibility; unlike the general Telegram group or forums, where important conversations are often lost.

We already have procedures for submitting bug reports and feature requests on GitHub. It may be worth introducing a third category: support tickets. This would allow users to seek help directly through GitHub instead of using the forums or general Telegram group, making it easier to track and revisit recurring issues.

To support this shift, I’ll refrain from posting technical issues in the general GhostBSD forums or Telegram group, as those conversations are too easily buried. 🙂

Why not use GhostBSD Forums for technical discussion?

GitHub issues are not well-suited to conversation. Neither are GitHub discussions.

vimanuelt

In the past, we have responded to questions directly where they were posted. Discussions in the GhostBSD-Dev Telegram group have highlighted a key issue: the outcomes of these conversations are not being captured. Specifically, the results of discussions, such as questions and their answers, are not being incorporated into the project's documentation.

Using the forum for discussions, including project related discussions and user questions, then moving those into project artifacts and documentation requests, seems reasonable. Since it is impossible to get everyone on a call together, using the forums make sense. Using Telegram for technical discussions has proven to be ineffective.

For GhostBSD documentation, for both project and community, I proposed that we serialize subjects by ID to improve technical communication.

GhostBSD Documentation Index (This is an example)

1000 — Basic Orientation
1100 What is GhostBSD?
1110 GhostBSD vs FreeBSD: Key Differences
1200 Downloading and Verifying the ISO
1210 Creating a Bootable USB (balenaEtcher, dd)
1300 Installing GhostBSD with the Installer
1310 Dual Booting GhostBSD with Windows/macOS
1400 First Boot and Welcome Tour
1500 Understanding Boot Menu and Recovery Options

2000 — Graphical Desktop Environments
2100 MATE Desktop Overview (Default)
2200 XFCE Community Edition
2300 Display Settings and Scaling Fixes
2310 Fixing Oversized or Tiny UI Elements
2400 Accessibility Features (High Contrast, Zoom)
2500 Customizing Themes, Fonts, and Icons

3000 — System Management Tools
3100 Software Station: Installing Applications
3110 Managing Packages with pkg
3200 Update Station: System and Security Updates
3300 Managing Users and Groups in GUI and CLI
3400 Services and Startup Applications
3500 GhostBSD Control Center Overview

4000 — Networking and Internet
4100 Wi-Fi and Ethernet Setup in Control Center
4110 Connecting to Hidden Networks
4200 VPN Setup (OpenVPN, WireGuard via GUI)
4300 Simple Firewall with GUI or pf.conf
4400 Network Troubleshooting Tools (ping, traceroute, netstat)
4500 Bluetooth Pairing and Device Management

5000 — Hardware Compatibility and Drivers
5100 GPU Driver Setup (Intel, NVIDIA, AMD)
5110 Troubleshooting GPU Acceleration
5200 Audio Devices, Sound Cards, and Volume Issues
5300 Printing and Scanning with CUPS and SANE
5400 Laptop Battery and Power Management
5500 USB Devices, External Drives, and Mounting

6000 — Storage and ZFS Management
6100 Disk Partitioning with Installer or gpart
6200 Using and Understanding ZFS (Default Filesystem)
6210 ZFS Snapshots and Rollbacks (GUI and CLI)
6300 Native ZFS Encryption for Data Security
6400 Creating Backups with zfs send, Timeshift, or rsync
6500 Auto-mounting External Drives with GVFS

7000 — Software Development on GhostBSD
7100 Installing Compilers and Build Tools (GhostBSD*-dev)
7200 Using FreeBSD Ports on GhostBSD (with Caution)
7300 Programming with Go, Python, Rust
7400 Creating Your Own GhostBSD Packages

8000 — Security and Privacy Tools
8100 Using doas Instead of sudo
8200 Enabling ASLR and Kernel Protections
8300 Recommended Security Settings and GUI Tools
8400 Password Management and GPG
8500 Recommended Privacy Apps (Tor Browser, Element, Mullvad VPN)

9000 — Troubleshooting and Recovery
9100 Boot Issues and Fixing the Bootloader
9200 Reading System Logs (/var/log, journalctl)
9300 Debugging Crashes and Freezes
9400 Checking Device Compatibility
9500 How to Ask for Help Effectively (Forums, Telegram, GitHub)

A000 — Advanced Topics for Power Users
A100 Creating Custom GhostBSD ISOs
A200 Using bhyve or VirtualBox to Run GhostBSD
A300 Shell Scripting with sh, fish, or zsh
A400 Configuring GELI for Additional Encrypted Volumes
A500 Using GhostBSD on ARM or Single-Board Computers

B000 — Community, Contribution, and Support
B100 How to Report Bugs and Feature Requests
B200 Contributing to GhostBSD Code or Documentation
B300 Translation and Localization Guidelines
B400 Community Conduct and Support Roles
B500 Supporting the Project (Donations, Mirrors, Feedback)

C000 — Reference, FAQs, and How-To Guides
C100 Frequently Asked Questions (FAQ)
C200 Command-Line Quick Reference
C300 Desktop Tips and Performance Tweaks
C400 Suggested Applications by Category
C500 GhostBSD vs Linux: Daily Workflow Differences

D000 — Project Artifacts and Infrastructure
D100 Release Process and Schedule
D200 ISO Build System and ghostbsd-build Repository
D300 Default System Configuration Files (rc.conf, sysctl.conf, etc.)
D400 Package Base (pkgbase) Layout and Policy
D500 Infrastructure Overview (Mirrors, CDN, Git Repos)
D600 Project Governance and Decision-Making Process
D700 Historical Releases and Change Logs
D800 License, Trademarks, and Legal Considerations

grahamperrin

Thanks!

At a glance, the groupings look OK.

I'd avoid numbering things. Numbers will change. The same for letters of the alphabet.

vimanuelt

grahamperrin
If we expand and refine the subject coverage, the numbering structure will naturally stabilize. As the documentation matures, we’ll have a clearer picture of where each topic belongs, making the SSID-style codes more consistent and meaningful.

We could enhance it further by:

Add a goal-driven angle:

By improving subject coverage and refining topic boundaries, we create a more intuitive documentation hierarchy. This not only helps the numbering fall into place but also makes the documentation easier to maintain and scale.

Mention feedback loops:

As we gather feedback from users and contributors, we can adjust and rebalance the structure. Over time, this will help the numbering settle into a logical, stable format.

Actionable next step:

Let’s start by identifying any gaps in subject coverage, then adjust the hierarchy where needed. Once the content is more complete, we can review the SSID codes for consistency and finalize the taxonomy.

vimanuelt

The initial approach is optimized for quick reference by end users and system administrators. However, if the objective is to organize data for computer scientists and software engineers, implementing a permuted index system can enable faster lookups and more efficient reference resolution. Information architecture should always be aligned with the specific needs and expectations of its intended audience. :-)

The following is an example of a permuted index, which can be generated using a Python script.