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

[benn]

Hi James,
Yes. I've noticed some of the pages becoming unwieldy too so your
suggestion is an inevitability. Having such collosal themes such as
ZFS, Dtrace, virtualisatiion, services, ... and more, hopefully, much
more to come and placing this all in one file makes it cumbersome for
the document writer. Moreover, when I'm reading up on something, I
ususally end up exporting just that section to its own file and using
the -f option to produce an epub of that one section.

However, it might be wise to keep related sections somehow together in
a kind of namespace. For example, if you split up a file, all new files
deriving from the original file share the same name prefix; or you
place all files into the same sub-directory.

> 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.
Most certainly.  Furthermore, when we begin to add an index, we'll see
more duplication of material and repitions can be replaced by a
reference to elsewhere.

Benn



On Sat, 2022-01-15 at 11:05 +0000, James Madgwick wrote:
> 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