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

[Andreas Wacknitz]

Am 16.01.22 um 11:02 schrieb benn:
Hi,

I have included the openindiana mailing list in this discussion as I
hope it will reach more interested people.

At the moment James is the only actual member of the documentation team
and thus naturally its head.
I would like to invite everybody to chime in with ideas and opinions
here, and of course after discussion formulate a plan and act upon.

Everybody is invited to enhance our documentation by creating pull
requests against our oi-docs repository at
https://github.com/OpenIndiana/oi-docs

Please keep in mind that James as the team lead of the documentation
team will have the final decision about what will be merged and what not.

Best regards,
Andreas

> 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
>
>
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> https://openindiana.org/mailman/listinfo/oi-dev