Ubuntu Server Guide: call for content and reviews

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Ubuntu Server Guide: call for content and reviews

Joshua Powers
Hi,

I want to announce the migration of the Ubuntu Server Guide source to
Discourse [1]. Now that the source migration is complete, during the
upcoming LTS cycle a new site will publish the Discourse topics and
automatically update when changes are made.

How can you help improve these documents? If you have not already, make
an account on Discourse and review pages, make comments, or propose
content for new topics. Members of the Server Guide Discourse category
can then review the changes and incorporate them. Start by viewing the
Introduction page [2] to get an idea of what topics exist already.

The Server Guide for the current LTS release [3] will remain in the
current location.

Thanks,
Josh

[1] https://discourse.ubuntu.com/c/server/guide
[2] https://discourse.ubuntu.com/t/introduction/11322
[3] https://help.ubuntu.com/lts/serverguide/
--
Ubuntu Server Engineering Manager
Canonical Ltd.

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
On 2019.09.12 13:26 Joshua Powers wrote:

> Hi,

Hi, Thanks for your hard work on this.

> I want to announce the migration of the Ubuntu Server Guide source to
> Discourse [1]. Now that the source migration is complete, during the
> upcoming LTS cycle a new site will publish the Discourse topics and
> automatically update when changes are made.
>
> How can you help improve these documents? If you have not already, make
> an account on Discourse and review pages, make comments, or propose
> content for new topics. Members of the Server Guide Discourse category
> can then review the changes and incorporate them. Start by viewing the
> Introduction page [2] to get an idea of what topics exist already.
>
> The Server Guide for the current LTS release [3] will remain in the
> current location.

I am surprised to see this rolling out already.

Should we add a note and link to this new stuff from here?:
https://help.ubuntu.com/index.html

The related doc team wiki pages will need updating.

Is it possible to publish a PDF version of the serverguide?

It is not easy to navigate, both from within one page,
wanting to go to the next page, and from the order of things on
the navigation page [2]. For example. If I am on the Samba - file server
page [6] and then want to go to the print server page. To me,
the "Suggested Topics" area makes no sense.

There are a great many dead links, and I don't know how many links
that should not be links. For example [4], see index.pl as a link and
??? as a non functioning link, but should go to [5].

On [1], one can sort by a bunch of things, but not "topic", which
is the only sort I would be interested in. I guess
it doesn't matter, as I'll use [2].

At some point (typically around 21.10), the 20.04 serverguide will need
to be split out as 22.04 specific edits need to be started. Won't we
want something like we have now where "lts" or "stable" always points
to the correct version of the web pages? Once 22.04 is released,
then "lts" would point to that version and one would need to force
"20.04" to get the older, but still active version. While not needed
for two years, it should be planned for now.

>
> [1] https://discourse.ubuntu.com/c/server/guide
> [2] https://discourse.ubuntu.com/t/introduction/11322
> [3] https://help.ubuntu.com/lts/serverguide/

[4] https://discourse.ubuntu.com/t/web-servers-apache/11510
[5] https://discourse.ubuntu.com/t/security-certificates/11885
[6] https://discourse.ubuntu.com/t/samba-file-server/11889

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: call for content and reviews

Bryce Harrington-8
On Thu, Sep 12, 2019 at 05:44:15PM -0700, Doug Smythies wrote:
> On 2019.09.12 13:26 Joshua Powers wrote:
> There are a great many dead links, and I don't know how many links
> that should not be links. For example [4], see index.pl as a link and
> ??? as a non functioning link, but should go to [5].

This is true, the links need some maintenance work.  I'm spotting
several classes of breakage, two of which you've mentioned:

 * Internal cross-linking.  I think the link you mention in [4] is this
   type.  The old documentation links to the Backup page,
   (https://help.ubuntu.com/lts/serverguide/preparing-to-install.html#backing-up)
   but I suppose the conversion process couldn't recalculate the link
   and left "???" as a placeholder?  Referring to the original doc
   should help identify where these should be pointed in the updated
   doc.

 * Macro reference links.  Guessing the wiki had some shortcuts, such as
   "[Ubuntu Web site](&ubuntu-web;)", that are resulting in empty links
   such as the one you point out on the Apache2 page.  I'm not sure
   discourse has such functionality, so may be more maintainable to
   simply replace these macros with direct links.

 * Outdated links.  Some links go to existing documentation, but for
   versions of software older than what we carry.  This doesn't seem to
   be an issue for the Apache2 page (it links to Apache 2.4 docs,
   and eoan has 2.4.41).  Obviously updating these is an important part
   of the maintenance work for this doc as it moves from one LTS to
   another.

 * Example links.  "www.ubunturocks.com" is used in this documentation
   as an example for configuring apache.  It doesn't look like this is
   intended to be displayed as a clickable link, however Discourse seems
   to be automatically linkifying it.  The ubunturocks.com website seems
   no longer online though, so the result is what appears to be a broken
   link.  If the link is turned into a pre-formatted link
   (i.e. `www.ubunturocks.com`) it should display better.  I also
   suspect using a more obviously generic url (e.g. `www.mynewsite.com`
   in this case) would be less likely to confuse readers in the future
   as websites come and go.

 * Book links.  The References section includes a link to O'Reilly's
   Apache Cookbook, however this points at the 1st edition rather than
   the current 3rd edition.  I suspect in nearly all cases we should be
   pointing at current editions of print materials, so book links even
   if they resolve correctly, should be doublechecked for currentness.

 * Dead external links.  I've spotted one or two cases of standard
   linkrot on a few pages, such as to now-missing blog posts or ezine
   articles.  I suspect for ease of maintenance in the future it may be
   best practice to avoid such links when possible, perhaps directly
   including that information into this guide.

While changing links over, may also be worth swapping in https links
instead of http ones, but only where it's feasible.  The Mod SSL docs
link, ironically enough, seems to have http but not https, however the
apache.org links all redirect to https so we may as use https in these
cases.

For the Apache2 page, I've gone ahead and fixed up all the items
mentioned above, but the above link maintenance process should be done
on each of the pages in the guide, and re-done every LTS.

Bryce

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: call for content and reviews

Joshua Powers
In reply to this post by Doug Smythies
Thanks for taking a look at the new site!

On 9/12/19 5:44 PM, Doug Smythies wrote:
> Should we add a note and link to this new stuff from here?:
> https://help.ubuntu.com/index.html
>

Yes please. I filed the following to track that:
https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+bug/1843945

> The related doc team wiki pages will need updating.
>

If you can point me at pages, we can help out here as well.

> Is it possible to publish a PDF version of the serverguide?
>

I know we can do an offline HTML document, I will need to confirm about
PDF as well.

> It is not easy to navigate, both from within one page,
> wanting to go to the next page, and from the order of things on
> the navigation page [2]. For example. If I am on the Samba - file server
> page [6] and then want to go to the print server page. To me,
> the "Suggested Topics" area makes no sense.
>

I agree, that navigating between the Discourse pages is not
straightforward. Using the introduction page is what I have also found
to be the easiest mechanism until we have the new site up.

> At some point (typically around 21.10), the 20.04 serverguide will need
> to be split out as 22.04 specific edits need to be started. Won't we
> want something like we have now where "lts" or "stable" always points
> to the correct version of the web pages? Once 22.04 is released,
> then "lts" would point to that version and one would need to force
> "20.04" to get the older, but still active version. While not needed
> for two years, it should be planned for now.
>

I will need to confirm the mechanism that will let us do this. On other
sites [1] that use this same model they have the ability to show
previous versions.

[1] https://old-docs.maas.io/2.5/en/

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
On 2019.09.13 13:06 Joshua Powers wrote:
> On 9/12/19 5:44 PM, Doug Smythies wrote:

>> The related doc team wiki pages will need updating.
>
> If you can point me at pages, we can help out here as well.

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGuide (obsolete anyhow)
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository/Members-Serverguide
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Checking
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Submitting

These pages don't get a lot of hits so we should assess the person power required
verses the benefit.

>> Is it possible to publish a PDF version of the serverguide?
>>
>
> I know we can do an offline HTML document, I will need to confirm about
> PDF as well.

A PDF version is highly desirable.

>> It is not easy to navigate, both from within one page,
>> wanting to go to the next page, and from the order of things on
>> the navigation page [2]. For example. If I am on the Samba - file server
>> page [6] and then want to go to the print server page. To me,
>> the "Suggested Topics" area makes no sense.
>>

> I agree, that navigating between the Discourse pages is not
> straightforward. Using the introduction page is what I have also found
> to be the easiest mechanism until we have the new site up.

Oh, I thought that was the new site. I guess it is just the source code?

>> At some point (typically around 21.10), the 20.04 serverguide will need
>> to be split out as 22.04 specific edits need to be started. Won't we
>> want something like we have now where "lts" or "stable" always points
>> to the correct version of the web pages? Once 22.04 is released,
>> then "lts" would point to that version and one would need to force
>> "20.04" to get the older, but still active version. While not needed
>> for two years, it should be planned for now.
>>
>
> I will need to confirm the mechanism that will let us do this. On other
> sites [1] that use this same model they have the ability to show
> previous versions.

Oh, I see via your [1] reference, that what ends up being published
is rather organized, and I guess I have only been looking at source
code so far, albeit formatted. (?).

I also see that it has a link to discourse which looks similar to
this stuff.

O.K. so now that I think I understand, why wouldn't or couldn't
the actual published version just be located at the same old spot?:

https://help.ubuntu.com/lts/serverguide/index.html

And if yes, we don't need to change the current landing page at all,
nor add a note. Users don't care where the source code resides.

> [1] https://old-docs.maas.io/2.5/en/

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
In reply to this post by Joshua Powers
On 2019.09.09 13:26 Joshua Powers wrote:

> I want to announce the migration of the Ubuntu Server Guide source to
> Discourse [1]. Now that the source migration is complete, during the
> upcoming LTS cycle a new site will publish the Discourse topics and
> automatically update when changes are made.

Hi Josh,

Hmmm... I see that you did the migration some time ago, and now
the discourse code is out of sync with the launchpad code.

How difficult or hard is it to re migrate two .xml files?
The other option is to manually re-sync revisions 372 and 373.
 
https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/372
https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/373

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: call for content and reviews

Bryce Harrington-8
On Sat, Sep 14, 2019 at 09:41:38AM -0700, Doug Smythies wrote:

> On 2019.09.09 13:26 Joshua Powers wrote:
>
> > I want to announce the migration of the Ubuntu Server Guide source to
> > Discourse [1]. Now that the source migration is complete, during the
> > upcoming LTS cycle a new site will publish the Discourse topics and
> > automatically update when changes are made.
>
> Hi Josh,
>
> Hmmm... I see that you did the migration some time ago, and now
> the discourse code is out of sync with the launchpad code.
>
> How difficult or hard is it to re migrate two .xml files?
> The other option is to manually re-sync revisions 372 and 373.
>  
> https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/372
> https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/373
>

The deltas don't look too bad, I can manual re-sync them next week if no
one beats me to it.

Bryce

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Ubuntu Server Guide: How to manage launchpad bug reoprts

Doug Smythies
In reply to this post by Joshua Powers
Hi,

For the serverguide discourse version what is the plan
for how launchpad bugs should be dealt with?

Let's use bug 1839717 as an example case.
I chose this bug report because it is so trivial.

What I want to do is fix the bug for the DocBook version,
but leave it active for the discourse version. This would normally
be done via entering "target to series" stuff into the bug report.
however, there is no such 20.04 series in launchpad.

Does anybody have suggestions?
I do not know if it possible or practical, but perhaps a dummy series
called "discourse" could be setup, that could be a target series.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
In reply to this post by Bryce Harrington-8
On 2019.09.13 12:45 Bryce Harrington wrote:

> On Thu, Sep 12, 2019 at 05:44:15PM -0700, Doug Smythies wrote:
>> On 2019.09.12 13:26 Joshua Powers wrote:
>
>> There are a great many dead links, and I don't know how many links
>> that should not be links. For example [4], see index.pl as a link and
>> ??? as a non functioning link, but should go to [5].
>
> This is true, the links need some maintenance work.  I'm spotting
> several classes of breakage, two of which you've mentioned:
>
> * Internal cross-linking.  I think the link you mention in [4] is this
>   type.  The old documentation links to the Backup page,
>   (https://help.ubuntu.com/lts/serverguide/preparing-to-install.html#backing-up)
>   but I suppose the conversion process couldn't recalculate the link
>   and left "???" as a placeholder?  Referring to the original doc
>   should help identify where these should be pointed in the updated
>   doc.

Even though Josh's original e-mail clearly stated it, I did not
realize that this stuff still needs to be compiled into an overall
HTML document. So I wonder if the ??? stuff will get sorted out
then?

There were some very cool yelp-check tools for the old mallard
Desktop help documentation that would identify any bad internal
or external links. I do not know if they can work on the final HTML.

...

> * Dead external links.  I've spotted one or two cases of standard
>   linkrot on a few pages, such as to now-missing blog posts or ezine
>   articles.  I suspect for ease of maintenance in the future it may be
>   best practice to avoid such links when possible, perhaps directly
>   including that information into this guide.

We have been trying to fix dead links as they are discovered.
And yes, it has always been serveguide policy to avoid external links
where possible. However, in many (most) cases it is unreasonable to
include the information directly, and we do not want to create a situation
where we have to edit the discourse source to reflect changes at
that external link.

...

> For the Apache2 page, I've gone ahead and fixed up all the items
> mentioned above, but the above link maintenance process should be done
> on each of the pages in the guide, and re-done every LTS.

Agreed. However, and based on past experience, this will not happen.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: How to manage launchpad bug reoprts

Bryce Harrington-8
In reply to this post by Doug Smythies
On Sun, Sep 15, 2019 at 08:42:40AM -0700, Doug Smythies wrote:

> Hi,
>
> For the serverguide discourse version what is the plan
> for how launchpad bugs should be dealt with?
>
> Let's use bug 1839717 as an example case.
> I chose this bug report because it is so trivial.
>
> What I want to do is fix the bug for the DocBook version,
> but leave it active for the discourse version. This would normally
> be done via entering "target to series" stuff into the bug report.
> however, there is no such 20.04 series in launchpad.
>
> Does anybody have suggestions?
> I do not know if it possible or practical, but perhaps a dummy series
> called "discourse" could be setup, that could be a target series.

From https://launchpad.net/serverguide/+series it looks like the intent
was to have one series per lts, but it is missing bionic, and given the
current documentation efforts I agree with you a new series should be
added.

You're right though we don't know what the 20.04 release name will be,
which suggests a series name would need to be either '20.04' or
'f-series' or similar, and then rename when the actual release name is
known.

For the current efforts, naming a series 'discourse' would work but
thinking ahead to 22.04 and future LTS's, it could get confusing, so I
think continuing the existing series naming traditions for serverguide
would have less chance of confusion.

Btw, thank you for pointing out the bug tracker, there seem to be some
really solid suggestions here.  It'll be great if we can give some of
these attention this cycle.  Doug, what are your thoughts on where we'd
bang for the buck to work on?

Bryce

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: How to manage launchpad bug reoprts

Doug Smythies
Hi Bryce,

Thanks for your reply.

On 2019.09.15 12:04 Bryce Harrington wrote:

> On Sun, Sep 15, 2019 at 08:42:40AM -0700, Doug Smythies wrote:
>> Hi,
>>
>> For the serverguide discourse version what is the plan
>> for how launchpad bugs should be dealt with?
>>
>> Let's use bug 1839717 as an example case.
>> I chose this bug report because it is so trivial.
>>
>> What I want to do is fix the bug for the DocBook version,
>> but leave it active for the discourse version. This would normally
>> be done via entering "target to series" stuff into the bug report.
>> however, there is no such 20.04 series in launchpad.
>>
>> Does anybody have suggestions?
>> I do not know if it possible or practical, but perhaps a dummy series
>> called "discourse" could be setup, that could be a target series.
>
> From https://launchpad.net/serverguide/+series it looks like the intent
> was to have one series per lts, but it is missing bionic,

Actually, bionic is not missing, but it is still called "trunk".
Why? Because we only allow the master "trunk" branch to diverge
from "bionic", when we absolutely have to, which is typically sometime
around now, as 20.04 specific edits might start to land. However, for
this cycle, "bionic' will never be split out of "trunk", because there
will never be a DocBook version of serverguide 20.04.

> and given the
> current documentation efforts I agree with you a new series should be
> added.
>
> You're right though we don't know what the 20.04 release name will be,
> which suggests a series name would need to be either '20.04' or
> 'f-series' or similar, and then rename when the actual release name is
> known.

> For the current efforts, naming a series 'discourse' would work but
> thinking ahead to 22.04 and future LTS's, it could get confusing, so I
> think continuing the existing series naming traditions for serverguide
> would have less chance of confusion.

Oh.
O.K. then I suggest, we split out "bionic" from "trunk", and continue
as we have done in the past: "trunk" will be called "trunk" until about
21.10 (or until we know what to change it to , if you prefer);
the actual content of "trunk" will be meaningless and is really
only used to support the existing bug reporting infrastructure.
Actually, I'll probably make a "bzr commit" deleting all content, but
leave behind a README file explaining.

> Btw, thank you for pointing out the bug tracker, there seem to be some
> really solid suggestions here.  It'll be great if we can give some of
> these attention this cycle.  Doug, what are your thoughts on where we'd
> bang for the buck to work on?

Sorry, but I don't know. I have been over my head with the serverguide
for years. Subject matter expert input is desperately desired/required.
For many years now the claim has been that it was difficulties with
the "DocBook" stuff that was one major stumbling block to more corrections,
revisions, and new content. I'm just hoping that is true. Perhaps naively,
I don't know, but I was hoping the entire server team would now start
picking away at the bug reports.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: How to manage launchpad bug reoprts

Doug Smythies
On 2019.09.15 14:30 Doug Smythies wrote:
> On 2019.09.15 12:04 Bryce Harrington wrote:
>> On Sun, Sep 15, 2019 at 08:42:40AM -0700, Doug Smythies wrote:

...

> O.K. then I suggest, we split out "bionic" from "trunk", and continue
> as we have done in the past: "trunk" will be called "trunk" until about
> 21.10 (or until we know what to change it to , if you prefer);

Done.
I had to do it twice, and so apologise if people got
redundant e-mails about it (probably only doc team committers, but
don't really know).

> the actual content of "trunk" will be meaningless and is really
> only used to support the existing bug reporting infrastructure.
> Actually, I'll probably make a "bzr commit" deleting all content, but
> leave behind a README file explaining.

Pending, just in case anyone wants to suggest something else.
Otherwise, I'll do this step in about 24 hours.

>> Btw, thank you for pointing out the bug tracker, there seem to be some
>> really solid suggestions here.  It'll be great if we can give some of
>> these attention this cycle.  Doug, what are your thoughts on where we'd
>> bang for the buck to work on?
>
> Sorry, but I don't know. I have been over my head with the serverguide
> for years. Subject matter expert input is desperately desired/required.
> For many years now the claim has been that it was difficulties with
> the "DocBook" stuff that was one major stumbling block to more corrections,
> revisions, and new content. I'm just hoping that is true. Perhaps naively,
> I don't know, but I was hoping the entire server team would now start
> picking away at the bug reports.

I forgot to mention, if it is really desirable that some fixes be backported
to the DocBook bionic version, I'll take care of it, depending on the volume
of work that evolves. I will not (and never have) backport to trusty.
Why don't we typically backport fixes? Because I am only one person, and can't
be bothered.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: How to manage launchpad bug reoprts

Bryce Harrington-8
In reply to this post by Doug Smythies
On Sun, Sep 15, 2019 at 02:29:37PM -0700, Doug Smythies wrote:
> On 2019.09.15 12:04 Bryce Harrington wrote:
> > From https://launchpad.net/serverguide/+series it looks like the intent
> > was to have one series per lts, but it is missing bionic,
>
> Actually, bionic is not missing, but it is still called "trunk".
>
> O.K. then I suggest, we split out "bionic" from "trunk", and continue
> as we have done in the past: "trunk" will be called "trunk" until about
> 21.10 (or until we know what to change it to , if you prefer);

That seems like a good suggestion to me, it sounds quite workable.

> Sorry, but I don't know. I have been over my head with the serverguide
> for years. Subject matter expert input is desperately desired/required.
> For many years now the claim has been that it was difficulties with
> the "DocBook" stuff that was one major stumbling block to more corrections,
> revisions, and new content. I'm just hoping that is true.

That, yes, and also the server team had been understaffed until
recently, but with both those resolved hopefully serverguide will start
getting more attention moving forward.  At least, the server guide
updating has been coming up in team meetings recurringly recently.  I
think it's safe to expect to see movement pick up through the rest of
the year.

> Perhaps naively, I don't know, but I was hoping the entire server team
> would now start picking away at the bug reports.

I'll try to make mention of these bug reports in any task prioritization
discussions that come up.  A lot of these do look like they'd be easy to
address, the bigger task is in adding missing content and deciding what
obsolete materials need culled.

I'm curious if moving to discourse will simplify the workflow to enable
more drive by copyedits to get incorporated more directly, but guess
we'll need to see how that evolves.

Thanks again, great ideas and suggestions.

Bryce

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: call for content and reviews

Bryce Harrington-8
In reply to this post by Bryce Harrington-8
On Sat, Sep 14, 2019 at 10:36:27AM -0700, Bryce Harrington wrote:

> On Sat, Sep 14, 2019 at 09:41:38AM -0700, Doug Smythies wrote:
> > Hmmm... I see that you did the migration some time ago, and now
> > the discourse code is out of sync with the launchpad code.
> >
> > How difficult or hard is it to re migrate two .xml files?
> > The other option is to manually re-sync revisions 372 and 373.
> >  
> > https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/372
> > https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/373
> >
>
> The deltas don't look too bad, I can manual re-sync them next week if no
> one beats me to it.

> > https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/372

Merged to https://discourse.ubuntu.com/t/installation-iscsi/11321

> > https://bazaar.launchpad.net/~ubuntu-core-doc/serverguide/trunk/revision/373

Merged to https://discourse.ubuntu.com/t/samba-active-directory/11893

Bryce

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
In reply to this post by Doug Smythies
Hi all,

There are still things to work out for this
transition from Docbook to discourse, but I thought it
best to wait until after 19.10 was done.

O.K. so now let's get on with it.

Where will the final compiled HTML document be posted?
And would it make sense to simply have it at the same location
as where the Docbook version would end up? That would be:

https://help.ubuntu.com/20.04/serverguide/index.html

during this preliminary phase, and become

https://help.ubuntu.com/lts/serverguide/index.html

after the release date.

Regardless of being in the old location or some new location,
Can we (meaning one of you) get on with it, such that compile,
formatting and publishing issues can be discovered and fixed now.

For testing purposes, and until the publishing step happens by
itself, how does one compile the discourse source code into what would
be the final html documents?

Can whomever please give me editing rights to the discourse stuff.

The answer to the question: Will a PDF version be available?
Was "I don't know". Can that answer be determined now?

I think I am forgetting some things. Oh well.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Ubuntu Server Guide: call for content and reviews

Joshua Powers
On 11/5/19 5:24 PM, Doug Smythies wrote:

> Hi all,
>
> There are still things to work out for this
> transition from Docbook to discourse, but I thought it
> best to wait until after 19.10 was done.
>
> O.K. so now let's get on with it.
>
> Where will the final compiled HTML document be posted?
> And would it make sense to simply have it at the same location
> as where the Docbook version would end up? That would be:
>
> https://help.ubuntu.com/20.04/serverguide/index.html
>
> during this preliminary phase, and become
>
> https://help.ubuntu.com/lts/serverguide/index.html
>
> after the release date.
>

I will be at a sprint next week where I will get an update on the
progress of the new site including the location and the PDF question
below. My hope was that the new site would be live right after the new
year, if not sooner.

> Regardless of being in the old location or some new location,
> Can we (meaning one of you) get on with it, such that compile,
> formatting and publishing issues can be discovered and fixed now.
>
> For testing purposes, and until the publishing step happens by
> itself, how does one compile the discourse source code into what would
> be the final html documents?
>
> Can whomever please give me editing rights to the discourse stuff.
>

By migrating to Discourse, anyone can make an account and then add
comments on the topics. Those comments can be suggestions, fixes, or
conversations about the content. Editors can then update the docs
themselves and those changes can be reflected immediately on the new
site.

The Canonical server team has already begun going through the existing
content removing or updating outdated pages, checking links, and
verifying the formatted pages.

This original thread was a call to action for content and reviews. I
continue to invite others to view the list of topics [1], review, and
contribute as we prepare for our next LTS release.

[1] https://discourse.ubuntu.com/t/introduction/11322

> The answer to the question: Will a PDF version be available?
> Was "I don't know". Can that answer be determined now?
>
> I think I am forgetting some things. Oh well.
>
> ... Doug
>
>


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Ubuntu Server Guide: call for content and reviews

Doug Smythies
Hi Josh,

Thank you for your reply.

On 2019.11.06 07:56 Josh wrote:

> On 11/5/19 5:24 PM, Doug Smythies wrote:
>>
>> There are still things to work out for this
>> transition from Docbook to discourse, but I thought it
>> best to wait until after 19.10 was done.
>>
>> O.K. so now let's get on with it.
>>
>> Where will the final compiled HTML document be posted?
>> And would it make sense to simply have it at the same location
>> as where the Docbook version would end up? That would be:
>>
>> https://help.ubuntu.com/20.04/serverguide/index.html
>>
>> during this preliminary phase, and become
>>
>> https://help.ubuntu.com/lts/serverguide/index.html
>>
>> after the release date.
>>
>
> I will be at a sprint next week where I will get an update on the
> progress of the new site including the location and the PDF question
> below. My hope was that the new site would be live right after the new
> year, if not sooner.

As soon as possible, so as to maximize the time to deal with
as yet unknown issues.

>> Regardless of being in the old location or some new location,
>> Can we (meaning one of you) get on with it, such that compile,
>> formatting and publishing issues can be discovered and fixed now.
>>
>> For testing purposes, and until the publishing step happens by
>> itself, how does one compile the discourse source code into what would
>> be the final html documents?

I do want to be able to compile the discourse source code into the
final HTML document, and PDF, myself.

>>
>> Can whomever please give me editing rights to the discourse stuff.
>>
>
> By migrating to Discourse, anyone can make an account and then add
> comments on the topics. Those comments can be suggestions, fixes, or
> conversations about the content. Editors can then update the docs
> themselves and those changes can be reflected immediately on the new
> site.

O.K. I just did a small, more or less a test, edit to:

https://discourse.ubuntu.com/t/virtualization-libvirt/11522

Which worked fine, but does raise another question.
How do we prevent abuse? (maybe I already have elevated rights?)
I am only familiar with the current system, where one
has to have sufficient rights to accept merge proposals and/or
push directly to the master branch.

> The Canonical server team has already begun going through the existing
> content removing or updating outdated pages, checking links, and
> verifying the formatted pages.

Yes, I see. This is great and what we have hoped for with this
conversion.

> This original thread was a call to action for content and reviews. I
> continue to invite others to view the list of topics [1], review, and
> contribute as we prepare for our next LTS release.

Yes, agree.

[1] https://discourse.ubuntu.com/t/introduction/11322

> The answer to the question: Will a PDF version be available?
> Was "I don't know". Can that answer be determined now?
>
> I think I am forgetting some things. Oh well.
>
> ... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc