Re: Finalizing server guide diataxis

[Christian Ehrhardt]

On Thu, Sep 29, 2022 at 12:41 AM Bryce Harrington
 wrote:
>
> On Wed, Sep 28, 2022 at 10:27:27AM -0700, Lena Voytek wrote:
> > Hello all,
> >
> > As I finish up the preparations for the Server Guide to transition to
> > diataxis, I was wondering if I could get your feedback on a few items.
> >
> > The first is the new home page. I created a page for its proposal here
> > 
> > (excluding the full navigation section), and can move its contents over to
> > the current home page  next, which will
> > automatically update the guide's navigation. It's meant to match the 
> > standard
> > homepage documentation
> > 
> > as closely as possible, similar to Ubuntu Core
> > . If there is anything that can be worded
> > better, or that is missing and should be there let me know!
> >
> > Second are the diataxis home pages: Tutorials
> > , How-to
> > guides ,
> > Explanations
> >  and
> > Reference .
> > These are meant to be similar to Ubuntu Core's sections: Tutorials
> > , How-to
> > , Explanation
> > , and Reference
> > .
> >
> > Lastly I would like your opinion on formatting for some of the existing
> > server guide pages. Many of our pages focus on individual packages, and
> > while doing so contain portions that vary in terms of what part of diataxis
> > they fall under. For example, in the Squid page
> > , the first two
> > paragraphs are an explanation, followed by the Installation and
> > Configuration sections which are technically tutorials, and ending with the
> > References section which of course falls under reference. There are two
> > main options I could move forward with here. The first would be to split
> > the page up to purely match diataxis, possibly adding some more depth to
> > the explanation, while creating a new page specifically as a tutorial for
> > installing/configuring the package. The second would be to leave the page
> > as it currently is and mark it as a reference. This would likely be easier
> > for users to follow since they would be able to reference all important
> > information about a given package without going to multiple pages. This
> > change would affect most single-page packages in the Services and Tools
> > section of the guide. Larger guides, however, such as OpenLDAP
> > , can be split
> > much more cleanly by page between the four categories.
>
> Hi Lena, first thanks for all the work and attention on this.  The
> restructuring work here looks overwhelming but you've given good though
> into how it can be organized.
>
> I don't have a deep knowledge of Diataxis, basically just a read-thru of
> https://diataxis.fr/ coupled with past experience with doc writing.
> Hopefully these thoughts aren't too far misaligned to be of use.
>
> Wearing the hat of a server user that would be consuming these different
> kinds of documents, and thinking about what currently exists in the
> Ubuntu Server Guide, honestly none of it matches what I'd expect as
> "Reference".  To me, "reference docs" for server stuff would be way more
> akin to man pages and --help text; I would not be unpleasantly surprised
> to find in Reference copies of upstream's reference docs, reformatted
> for Ubuntu's website (along the lines of readthedocs.org).  Much of what
> we currently have is too piecemeal and narratively structured to be what
> I would consider proper reference.  In particular, the lists of
> "reference" links to external resources to be "Reference Documentation";
> they are more just "See Also" links.
>
> Honestly I don't think the Server Team is really contituted in a way
> that lends itself to writing and maintaining reference documentation,
> with the exception *maybe* of software Canonical develops and maintains
> itself like Curtin.
>
> So for the Reference section, I kind of am of the mind that this section
> should start empty and maybe should be populated by auto-generating what
> the upstream provides in the versions of packages included in the given
> LTS release.  As a user, having all the upstream docs reliably gathered
> together in one place, with consistent formatting (and maybe even
> cross-referencing!) would be a big value-add.
>
>
> To me, the authorial intent of the Ubuntu Server Guide aims to something
> in between 

Re: Finalizing server guide diataxis

[Bryce Harrington]

On Wed, Sep 28, 2022 at 10:27:27AM -0700, Lena Voytek wrote:
> Hello all,
> 
> As I finish up the preparations for the Server Guide to transition to
> diataxis, I was wondering if I could get your feedback on a few items.
> 
> The first is the new home page. I created a page for its proposal here
> 
> (excluding the full navigation section), and can move its contents over to
> the current home page  next, which will
> automatically update the guide's navigation. It's meant to match the standard
> homepage documentation
> 
> as closely as possible, similar to Ubuntu Core
> . If there is anything that can be worded
> better, or that is missing and should be there let me know!
> 
> Second are the diataxis home pages: Tutorials
> , How-to
> guides ,
> Explanations
>  and
> Reference .
> These are meant to be similar to Ubuntu Core's sections: Tutorials
> , How-to
> , Explanation
> , and Reference
> .
> 
> Lastly I would like your opinion on formatting for some of the existing
> server guide pages. Many of our pages focus on individual packages, and
> while doing so contain portions that vary in terms of what part of diataxis
> they fall under. For example, in the Squid page
> , the first two
> paragraphs are an explanation, followed by the Installation and
> Configuration sections which are technically tutorials, and ending with the
> References section which of course falls under reference. There are two
> main options I could move forward with here. The first would be to split
> the page up to purely match diataxis, possibly adding some more depth to
> the explanation, while creating a new page specifically as a tutorial for
> installing/configuring the package. The second would be to leave the page
> as it currently is and mark it as a reference. This would likely be easier
> for users to follow since they would be able to reference all important
> information about a given package without going to multiple pages. This
> change would affect most single-page packages in the Services and Tools
> section of the guide. Larger guides, however, such as OpenLDAP
> , can be split
> much more cleanly by page between the four categories.

Hi Lena, first thanks for all the work and attention on this.  The
restructuring work here looks overwhelming but you've given good though
into how it can be organized.

I don't have a deep knowledge of Diataxis, basically just a read-thru of
https://diataxis.fr/ coupled with past experience with doc writing.
Hopefully these thoughts aren't too far misaligned to be of use.

Wearing the hat of a server user that would be consuming these different
kinds of documents, and thinking about what currently exists in the
Ubuntu Server Guide, honestly none of it matches what I'd expect as
"Reference".  To me, "reference docs" for server stuff would be way more
akin to man pages and --help text; I would not be unpleasantly surprised
to find in Reference copies of upstream's reference docs, reformatted
for Ubuntu's website (along the lines of readthedocs.org).  Much of what
we currently have is too piecemeal and narratively structured to be what
I would consider proper reference.  In particular, the lists of
"reference" links to external resources to be "Reference Documentation";
they are more just "See Also" links.

Honestly I don't think the Server Team is really contituted in a way
that lends itself to writing and maintaining reference documentation,
with the exception *maybe* of software Canonical develops and maintains
itself like Curtin.

So for the Reference section, I kind of am of the mind that this section
should start empty and maybe should be populated by auto-generating what
the upstream provides in the versions of packages included in the given
LTS release.  As a user, having all the upstream docs reliably gathered
together in one place, with consistent formatting (and maybe even
cross-referencing!) would be a big value-add.


To me, the authorial intent of the Ubuntu Server Guide aims to something
in between Tutorial and How-To, with most pages leaning more towards the
former than the latter.  I might even go so far as to suggest that all
the current pages be put into Tutorials and then go through one-by-one
and extract any text