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 

Finalizing server guide diataxis

[Lena Voytek]

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.

Thanks,
Lena
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

Wednesday Triage Report (2022-09-28)

[Sergio Durigan Junior]

ustriage found 12 bugs.  These are the noteworthy ones:

### https://pad.lv/1979081 - *+(Triaged) [adcli] - domain join with
--use-ldaps still uses port 389 for LDAP p…

Upstream fixed the issue.  This is a low priority bug; we can certainly
fix it in the next development release, but for and SRU this would need
to be uploaded along with other (more important) fixes.


### https://pad.lv/1959581 - *(Confirmed) [ocfs2-tools] - OCFS2
intermittently not mountable on a second Node in Ubun…

This one is making a comeback because it's affecting more users.  I see
that mfo is (was?) working on it.  I'll ping him to see the status.


### https://pad.lv/1969654 - *(Fix Released) [samba] - Can't print with
Samba via Windows 10 printer after 2:4.13.…

Just a heads up that I've marked this as Fix Released since the reporter
confirmed that the issue was solved.

-- 
Sergio
GPG key ID: E92F D0B3 6B14 F1F4 D8E0  EB2F 106D A1C8 C3CB BF14


signature.asc
Description: PGP signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

Re: Tuesday Bug Triage Report (2022-09-27)

[Robie Basak]

Well done on your first triage, and good job with writing up the report.
It's particularly valuable as it enables wider feedback on this list.

On Wed, Sep 28, 2022 at 10:08:58AM +0200, Michał Małoszewski wrote:
> *https://pad.lv/1980466  - (Confirmed)
>  [mysql-8.0]- mysql_secure_installation can not set root
> password and end…*
> Here I was very careful when I've noticed that it's mysql issue. I have
> added workaround for it in the comment sections.
> @Robie Basak , @Lena Voytek
>  could you take a look at this bug and maybe
> suggest or prompt if there is a way to improve the workaround or the
> solution in general.

I don't think running mysql_secure_installation makes sense on Ubuntu
(or Debian) - certainly not straight after installation - because
package maintainer scripts arrange to set secure defaults themselves.
Setting a root password reduces security because by default only Unix
socket authentication is permitted, which is guaranteed, rather than
relying on a secret that could be guessed or brute forced.

However I can understand how a user, guided by upstream or external
docs, would think that's an appropriate step that should be followed,
then see it fail, and then think that there's a bug. That's a poor UX,
and a poor UX is a valid bug.

I wonder if we should perhaps stop shipping mysql_secure_installation
entirely? Or, if it does something useful that someone might want to
run, then what can be adjusted to make this a better UX for users who
fall into this trap? This might be worth discussing with upstream.

> *https://pad.lv/1990863  - (New)
> [openssh]  - conversion from sshd service to socket is too
> bumpy*
> Here I didn't comment that one because I was unsure about it. I mean: I
> think that this person should list the steps to reproduce it easily apart
> from writing the scope of the problem.
> Honestly, in my opinion that description is a bit overwhelming.
> Lucas asked for more information, especifically their changes in the config
> file so we can better investigate the upgrade path they are going through.

I'm familiar with this. Steve is working on the move to socket
activation, so I commented and also subscribed Steve.


signature.asc
Description: PGP signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

Re: Tuesday Bug Triage Report (2022-09-27)

[Miriam Espana Acebal]

Congrats on your first Triage Report, Michał!

On Wed, Sep 28, 2022 at 10:10 AM Michał Małoszewski <
michal.maloszew...@canonical.com> wrote:

> Hi all,
>
> Here is my first triage report.
> I've added my comment to each bug url below to show you my way of thinking
> and that the results didn't come out of the blue.
> My report's been reviewed by Lucas, who was in charge of the bug triage
> that day.
>
> Bugs last updated on 2022-09-26 (Monday)
> Date range identified as: "Tuesday triage"
> Found 7 bugs
>
> *https://pad.lv/1978064  - +(Confirmed)
>  [libvirt]   - [Libvirt} IceLake CPU model not
> recognized*
> So here, Lena takes care of that bug and the last comment has been added
> +- 13 hours ago.
> The status in each release is marked well. (The comments show it)
> Nothing to add here.
>
> *https://pad.lv/1983605  - *+(Triaged)
> [exim4]  - exim4 autopkgtest failure on ppc64el*
> The bug verified by Sergio and last comment from Bryce some hours ago. I
> have nothing to add here.
>
> *https://pad.lv/1990668  - +(Incomplete)
> [python-oauthlib]   - package python3-oauthlib 3.2.0-1ubuntu0.1 failed
> to install…*
> I have nothing to add here. Bug reported 4 days ago by Luis Rodriguez and
> it was checked by Sergio. Waiting for feedback.
>
> *https://pad.lv/1980466  - (Confirmed)
>  [mysql-8.0]- mysql_secure_installation can not set root
> password and end…*
> Here I was very careful when I've noticed that it's mysql issue. I have
> added workaround for it in the comment sections.
> @Robie Basak , @Lena Voytek
>  could you take a look at this bug and maybe
> suggest or prompt if there is a way to improve the workaround or the
> solution in general.
>
> *https://pad.lv/1982727  - *(Won't Fix)
>  [iotop]- IOTOP can not work due to
> CONFIG_TASK_DELAY_ACCT not enable…*
> (I take care of that bug and I have added comment from my recent status)
>
> *https://pad.lv/1990853  - (New)
> [libvirt]   - uvt-kvm: error: libvirt: Requested
> operation is not valid: …*
> This bug reporter seems to be really self-confident and his karma is
> really high. So honestly what I would do here is to try to reproduce what
> he has written and think about new steps or ping someone who is experienced
> in that kind of things.
> Lucas reproduced the bug and added a comment there with more detailed
> steps. Also a new task for uvtool was added by Lucas and marked as Triaged.
> Bug added to our backlog.
>
> *https://pad.lv/1990863  - (New)
> [openssh]  - conversion from sshd service to socket is too
> bumpy*
> Here I didn't comment that one because I was unsure about it. I mean: I
> think that this person should list the steps to reproduce it easily apart
> from writing the scope of the problem.
> Honestly, in my opinion that description is a bit overwhelming.
> Lucas asked for more information, especifically their changes in the
> config file so we can better investigate the upgrade path they are going
> through.
>
> Best Regards,
> Michał Małoszewski
> --
> ubuntu-server mailing list
> ubuntu-server@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
> More info: https://wiki.ubuntu.com/ServerTeam



-- 
Miriam España Acebal
Software Engineer I - Ubuntu PublicCloud/Server
Canonical Ltd.
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

Tuesday Bug Triage Report (2022-09-27)

[Michał Małoszewski]

Hi all,

Here is my first triage report.
I've added my comment to each bug url below to show you my way of thinking
and that the results didn't come out of the blue.
My report's been reviewed by Lucas, who was in charge of the bug triage
that day.

Bugs last updated on 2022-09-26 (Monday)
Date range identified as: "Tuesday triage"
Found 7 bugs

*https://pad.lv/1978064  - +(Confirmed)
 [libvirt]   - [Libvirt} IceLake CPU model not
recognized*
So here, Lena takes care of that bug and the last comment has been added +-
13 hours ago.
The status in each release is marked well. (The comments show it)
Nothing to add here.

*https://pad.lv/1983605  - *+(Triaged)
[exim4]  - exim4 autopkgtest failure on ppc64el*
The bug verified by Sergio and last comment from Bryce some hours ago. I
have nothing to add here.

*https://pad.lv/1990668  - +(Incomplete)
[python-oauthlib]   - package python3-oauthlib 3.2.0-1ubuntu0.1 failed
to install…*
I have nothing to add here. Bug reported 4 days ago by Luis Rodriguez and
it was checked by Sergio. Waiting for feedback.

*https://pad.lv/1980466  - (Confirmed)
 [mysql-8.0]- mysql_secure_installation can not set root
password and end…*
Here I was very careful when I've noticed that it's mysql issue. I have
added workaround for it in the comment sections.
@Robie Basak , @Lena Voytek
 could you take a look at this bug and maybe
suggest or prompt if there is a way to improve the workaround or the
solution in general.

*https://pad.lv/1982727  - *(Won't Fix)
 [iotop]- IOTOP can not work due to
CONFIG_TASK_DELAY_ACCT not enable…*
(I take care of that bug and I have added comment from my recent status)

*https://pad.lv/1990853  - (New)
[libvirt]   - uvt-kvm: error: libvirt: Requested
operation is not valid: …*
This bug reporter seems to be really self-confident and his karma is really
high. So honestly what I would do here is to try to reproduce what he has
written and think about new steps or ping someone who is experienced in
that kind of things.
Lucas reproduced the bug and added a comment there with more detailed
steps. Also a new task for uvtool was added by Lucas and marked as Triaged.
Bug added to our backlog.

*https://pad.lv/1990863  - (New)
[openssh]  - conversion from sshd service to socket is too
bumpy*
Here I didn't comment that one because I was unsure about it. I mean: I
think that this person should list the steps to reproduce it easily apart
from writing the scope of the problem.
Honestly, in my opinion that description is a bit overwhelming.
Lucas asked for more information, especifically their changes in the config
file so we can better investigate the upgrade path they are going through.

Best Regards,
Michał Małoszewski
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam