Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Splitting existing pages into multiple pages #211

Open
JMadgwick opened this issue Dec 28, 2021 · 1 comment
Open

Splitting existing pages into multiple pages #211

JMadgwick opened this issue Dec 28, 2021 · 1 comment
Labels

Comments

@JMadgwick
Copy link
Contributor

The Getting Started and Systems Administration pages have a lot of content packed into a single page. This doesn't seem like the best way to organise things.
In particular there is still content on ZFS and Virtualization that could be migrated from the old Wiki. There are placeholders in the docs where this could go, but it would make the pages even longer.
It seems like the content could be split across a few more pages, so that storage and zones/virtualization could have their own pages.

@JMadgwick
Copy link
Contributor Author

On the OI-Dev mailing list @cstes mentioned the OI handbook is based on the FreeBSD handbook.

This is a breakdown of the existing high level sections in each of the 5 pages which make up the OI handbook:

  • Getting Started
    1 Introduction
    2 Conventions
    3 Hipster Software Releases
    4 System Requirements
    5 Exploring OpenIndiana Hipster
    6 Preparing to Install Hipster
    7 Creating a Hipster DVD
    8 Creating a Hipster USB Drive
    9 Booting the Hipster Installer
    10 Installing OpenIndiana
    11 Troubleshooting Installations
    12 Post Installation Steps
    13 Updating OpenIndiana /dev to /hipster
    14 Image Package System (IPS)
    15 Managing Boot Environments
    16 The XWindow System
    17 Device Drivers
  • Common Tasks
    1 Basic UNIX commands
    2 Basic system administration
    3 Desktop applications
    4 Multimedia Audio
    5 Multimedia Video
    6 Printing
    7 Graphics workstation
    8 Desktop Publishing system, Etc.
    9 Boot loader settings
  • Systems Administration
    1 Users and account management
    2 Management of System Resources
    3 Configuring and Tuning
    4 Illumos boot process
    5 Security
    6 Zones
    7 Storage
    8 Virtualization
    9 Localization
    10 Dtrace
    11 Configuring Networking
    12 Clustering with Open HA Cluster
  • Network Communications
    1 PPP
    2 PPPoE
    3 Email
    4 WWW server
    5 Firewalls
    6 NAT (Network Address Translation)
    7 Advanced Networking
    8 Crossbow
    9 Hipster as a NAS
    10 Hipster as an NIS server
    11 Hipster as an LDAP server
    12 Hipster as a DHCP server
    13 Hipster as an FTP server
    14 Hipster as a DNS server
    15 Hipster as a NTP server
    16 Hipster as a INETD server
  • Appendix
    1 Glossary
    2 Finding Help and Support
    3 IPS Command Matrix
    4 Developing with OpenIndiana
    5 Software Development

The FreeBSD has a page for each chapter (plus appendix) as below:

  • Part I. Getting Started
    Chapter 1. Introduction
    Chapter 2. Installing FreeBSD
    Chapter 3. FreeBSD Basics
    Chapter 4. Installing Applications: Packages and Ports
    Chapter 5. The X Window System
  • Part II. Common Tasks
    Chapter 6. Desktop Applications
    Chapter 7. Multimedia
    Chapter 8. Configuring the FreeBSD Kernel
    Chapter 9. Printing
    Chapter 10. Linux Binary Compatibility
    Chapter 11. WINE
  • Part III. System Administration
    Chapter 12. Configuration and Tuning
    Chapter 13. The FreeBSD Booting Process
    Chapter 14. Security
    Chapter 15. Jails
    Chapter 16. Mandatory Access Control
    Chapter 17. Security Event Auditing
    Chapter 18. Storage
    Chapter 19. GEOM: Modular Disk Transformation Framework
    Chapter 20. The Z File System (ZFS)
    Chapter 21. Other File Systems
    Chapter 22. Virtualization
    Chapter 23. Localization - i18n/L10n Usage and Setup
    Chapter 24. Updating and Upgrading FreeBSD
    Chapter 25. DTrace
    Chapter 26. USB Device Mode / USB OTG
  • Part IV. Network Communication
    Chapter 27. Serial Communications
    Chapter 28. PPP
    Chapter 29. Electronic Mail
    Chapter 30. Network Servers
    Chapter 31. Firewalls
    Chapter 32. Advanced Networking
  • Part V. Appendices
    Appendix A. Obtaining FreeBSD
    Appendix B. Bibliography
    Appendix C. Resources on the Internet
    Appendix D. OpenPGP Keys
    FreeBSD Glossary

The OI handbook has much less content than the FreeBSD handbook, so it wouldn't make sense to split everything down to the same level. I think it would be best to split the 4 main pages into 2-4 sub pages/chapters and to use the 'Part/Chapter' terminology. This reorganization would be a good opportunity to consolidate a few areas of duplication.

It may be worth investigating if the webpage navigation for the handbook can also be made to be more like FreeBSD - this is more suitable for this content than the existing drop down menubar.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant