OpenIndiana
Splitting existing pages into multiple pages
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.
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.