[oi-dev] Proposal to change documentation structure for some pages

[stes@PANDORA.BE]

I don't know how the docs ("handbook") was made, but I am under the impression that it attempts to follow the structure of the FreeBSD Handbook.

For FreeBSD there are several parts,

Part I. Getting Started
Part II. Common Tasks
Part III. System Administration
Part IV. Network Communication
Part V. Appendices

They have their ZFS chapter (for FreeBSD) as "Chapter 20. The Z File System (ZFS)" in part III.

So the pages for the OpenIndiana docs "getting started" and "system administration" and "network communications" correspond with the Parts of the FreeBSD handbook; but a division in chapters like FreeBSD is doing, could be a good idea ...

Regards,
David Stes


----- Op 15 jan 2022 om 12:05 schreef James Madgwick james at madgwick.xyz:

> Hi,
> 
> I've added an issue (https://github.com/OpenIndiana/oi-docs/issues/211)
> which proposes splitting some of the docs content into separate pages.
> 
> In particular I noticed it when formatting some content from the old
> Wiki for transfer. There's quite a bit covering ZFS to migrate, putting
> it all into an existing page would increase the length significantly.
> 
> My concern is there's a lot of content packed into a single page in
> some cases and this is not the easiest to navigate. It is not entirely
> clear which topics are covered by which page in the handbook - there is
> some overlap.
> 
> It might be possible to keep the same number of pages and instead
> investigate changes to the layout/theme in MkDocs; so it is easier to
> find subsections. Some content could maybe move between the sections
> where appropriate.
> 
> 
> Thanks,
> James
> 
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> https://openindiana.org/mailman/listinfo/oi-dev