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