Help page design, and the future of the Ubuntu Desktop Guide

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

Help page design, and the future of the Ubuntu Desktop Guide

Matthew Paul Thomas-2
As promised during the meeting on Saturday (Friday, for many of you),
I've written a wiki page on how I think we should write and arrange
help pages for maximum usefulness.
<https://wiki.ubuntu.com/UbuntuHelp/PageStructure>

As I described last month, the ideal structure, style, and content for
help pages -- and for a local help system as a whole -- is quite
different from the usual structure, style, and content for a printed
book.
<https://lists.ubuntu.com/archives/ubuntu-doc/2006-June/006585.html>

So if we're going to start adapting the Ubuntu Desktop Guide to this
structure, I can think of three options for the printed version.
(1) Fork it from the on-screen version, so that it can be given proper
     book treatment (chapters, footnotes, screenshots, diagrams, etc).
(2) Continue it as a quirkier, recipe-book-style, printed copy of every
     help page, without chapter introductions and the like.
(3) Retire it, leaving the job of publishing books to Apress, O'Reilly,
     Canonical and Prentice Hall, Addison-Wesley, etc.
     <http://urlx.org/amazon.com/d9ea0>

--
Matthew Paul Thomas
http://mpt.net.nz/


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Matthew East
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi!

* Matthew Paul Thomas:
> As promised during the meeting on Saturday (Friday, for many of you),
> I've written a wiki page on how I think we should write and arrange help
> pages for maximum usefulness.
> <https://wiki.ubuntu.com/UbuntuHelp/PageStructure>

This is all good stuff, and we should certainly aim for this. However,
I'm not sure whether we can achieve a help system that is wholly
compatible with these ideas by Edgy.

We currently have a number of docbook books (Desktop Guide, Server
guide, etc). These don't really allow us very easily to keep short pages
as described in the above link without undertaking a comprehensive
rehash of the structure of the documentation.

At the beginning of the release cycle I thought that such a rehash would
be a good idea, but now, I feel that there is not sufficient time to do
it properly, and we need to look for a compromise.

This is especially so because upstream will soon be doing the rehash
themselves, providing us with a new working structure, and I think it
makes sense for us to do this at the same time.

For the next release, what I propose we do is this:

 * Generally speaking, work with the existing guides but bear in mind
Matthew's comments about how to write good help, and improve the guides
accordingly.
 * Eliminate any overlap between the guides, and identify ways to
present a coherent front page. So, for example, it might include:

Adding, Removing and Updating Software in Ubuntu [1]
Working with your Desktop [2]
Working with a Server [3]
Getting more help [4]
Contributing to Ubuntu [5]

[1] An article, based on what is currently in the desktop guide
[2] A book, what is now the desktop guide
[3] A book, what is now the server guide
[4] An article, based on what is currently in the desktop guide
[5] An article, potentially new, which includes a link to the packaging
guide.

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFExiVNtSaF0w5rBv8RAi5UAJ9Rv4ZYV1h/f9KAtn+L4OwvYP2a6QCfeun1
JFI1j671xttRVHsiCgi1mpk=
=yeeY
-----END PGP SIGNATURE-----


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Jordan Mantha
<snippage>

> For the next release, what I propose we do is this:
>
>  * Generally speaking, work with the existing guides but bear in mind
> Matthew's comments about how to write good help, and improve the guides
> accordingly.
>  * Eliminate any overlap between the guides, and identify ways to
> present a coherent front page. So, for example, it might include:
>
> Adding, Removing and Updating Software in Ubuntu [1]
> Working with your Desktop [2]
> Working with a Server [3]
> Getting more help [4]
> Contributing to Ubuntu [5]
>
> [1] An article, based on what is currently in the desktop guide
> [2] A book, what is now the desktop guide
> [3] A book, what is now the server guide
> [4] An article, based on what is currently in the desktop guide
> [5] An article, potentially new, which includes a link to the packaging
> guide.

I think Andreas and I (at least) would be interested in [5]. We could do
a small (or big even) article that covers different ways people can
contribute to Ubuntu, perhaps an overview of each of the Ubuntu teams
with contact info. Something fairly similar to [0] but different, of
course. ;-)

-Jordan Mantha

[0] http://www.ubuntu.com/community/participate

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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Andreas Lloyd
Jordan Mantha wrote:

>> For the next release, what I propose we do is this:
>>
>>  * Generally speaking, work with the existing guides but bear in mind
>> Matthew's comments about how to write good help, and improve the guides
>> accordingly.
>>  * Eliminate any overlap between the guides, and identify ways to
>> present a coherent front page. So, for example, it might include:
>>
>> Adding, Removing and Updating Software in Ubuntu [1]
>> Working with your Desktop [2]
>> Working with a Server [3]
>> Getting more help [4]
>> Contributing to Ubuntu [5]
>>
>> [1] An article, based on what is currently in the desktop guide
>> [2] A book, what is now the desktop guide
>> [3] A book, what is now the server guide
>> [4] An article, based on what is currently in the desktop guide
>> [5] An article, potentially new, which includes a link to the packaging
>> guide.
>>    
I think this is a really good approach. If we can agree on this, I would
like to reorganize the the Projects page in the Wiki to reflect this
structure [https://wiki.ubuntu.com/DocumentationTeam/Projects].

Such a reorganization should show what goes into the Ubuntu docs and
what goes into the Kubuntu docs - and what goes into both - such as the
Server and Packaging guides. Once we have the overall structure to work
towards and have people assigned to each document, it will be a lot
easier to get the editing and rewriting of the current docs underway to
fit that structure.

> I think Andreas and I (at least) would be interested in [5]. We could do
> a small (or big even) article that covers different ways people can
> contribute to Ubuntu, perhaps an overview of each of the Ubuntu teams
> with contact info. Something fairly similar to [0] but different, of
> course. ;-)
>  
Yes, we have a few ideas to make such a contribute page work well in
another format that the one currently on the website.
Though I am not familiar with KHelpcenter, nor do I know if there are
Kubuntu-specific ways to contribute. Jonathan, I hope you'd up for
helping us with making the Contribute article work with Kubuntu as well.

Andreas

--
https://launchpad.net/people/lloydinho


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Jonathan Jesse-2
On Wednesday 26 July 2006 08:47, Andreas Lloyd wrote:

> Jordan Mantha wrote:
> >> For the next release, what I propose we do is this:
> >>
> >>  * Generally speaking, work with the existing guides but bear in mind
> >> Matthew's comments about how to write good help, and improve the guides
> >> accordingly.
> >>  * Eliminate any overlap between the guides, and identify ways to
> >> present a coherent front page. So, for example, it might include:
> >>
> >> Adding, Removing and Updating Software in Ubuntu [1]
> >> Working with your Desktop [2]
> >> Working with a Server [3]
> >> Getting more help [4]
> >> Contributing to Ubuntu [5]
> >>
> >> [1] An article, based on what is currently in the desktop guide
> >> [2] A book, what is now the desktop guide
> >> [3] A book, what is now the server guide
> >> [4] An article, based on what is currently in the desktop guide
> >> [5] An article, potentially new, which includes a link to the packaging
> >> guide.
>
> I think this is a really good approach. If we can agree on this, I would
> like to reorganize the the Projects page in the Wiki to reflect this
> structure [https://wiki.ubuntu.com/DocumentationTeam/Projects].
>
> Such a reorganization should show what goes into the Ubuntu docs and
> what goes into the Kubuntu docs - and what goes into both - such as the
> Server and Packaging guides. Once we have the overall structure to work
> towards and have people assigned to each document, it will be a lot
> easier to get the editing and rewriting of the current docs underway to
> fit that structure.
>
> > I think Andreas and I (at least) would be interested in [5]. We could do
> > a small (or big even) article that covers different ways people can
> > contribute to Ubuntu, perhaps an overview of each of the Ubuntu teams
> > with contact info. Something fairly similar to [0] but different, of
> > course. ;-)
>
> Yes, we have a few ideas to make such a contribute page work well in
> another format that the one currently on the website.
> Though I am not familiar with KHelpcenter, nor do I know if there are
> Kubuntu-specific ways to contribute. Jonathan, I hope you'd up for
> helping us with making the Contribute article work with Kubuntu as well.
>
> Andreas
>
> --
> https://launchpad.net/people/lloydinho

Andreas,

I can sure help make the Contribute article work w/ Kubuntu as well.  In fact
I want to make sure we continue to make sure to include kubuntu docs as well
in the discussion of things.

Don't forget the SwitchingFromWindows Guide as well that we are working on
puting into place.

Jonathan

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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Matthew East
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

> On Wednesday 26 July 2006 08:47, Andreas Lloyd wrote:
>> Yes, we have a few ideas to make such a contribute page work well in
>> another format that the one currently on the website.
>> Though I am not familiar with KHelpcenter, nor do I know if there are
>> Kubuntu-specific ways to contribute. Jonathan, I hope you'd up for
>> helping us with making the Contribute article work with Kubuntu as well.

As long as you write it as a docbook article it will be fine to work
with Kubuntu. Thanks for agreeing to work on this!

* Jonathan Jesse:
> I can sure help make the Contribute article work w/ Kubuntu as well.  In fact
> I want to make sure we continue to make sure to include kubuntu docs as well
> in the discussion of things.

There is nothing wrong with having separate discussions about what to do
with Ubuntu and Kubuntu - they are different help systems, so discussion
about how to present the start page of the help system will often be
separate, because it involves different technical considerations.

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEx2tItSaF0w5rBv8RAqZ2AJ9yyCzJra++KyxVBLHRV3ou556WpwCeLY8O
zhvCSxu4P9xJ4Kh+HxExHZ8=
=7aU0
-----END PGP SIGNATURE-----


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Andreas Lloyd
Matthew East wrote:
> As long as you write it as a docbook article it will be fine to work
> with Kubuntu. Thanks for agreeing to work on this!
>

Jordan and I will have to confer some more on this, but I'm sure we'll
get a draft done soon.

> * Jonathan Jesse:
> >> I can sure help make the Contribute article work w/ Kubuntu as
> well.  In fact
> >> I want to make sure we continue to make sure to include kubuntu
> docs as well
> >> in the discussion of things.

Great! It would be really nice if we can have one single doc to refer
people to, regardless of what derivative they might be using.


> There is nothing wrong with having separate discussions about what to do
> with Ubuntu and Kubuntu - they are different help systems, so discussion
> about how to present the start page of the help system will often be
> separate, because it involves different technical considerations.

Because of this, I have now reorganized the
https://wiki.ubuntu.com/DocumentationTeam/Projects. The projects are now
sorted into 4 categories:

- Ubuntu Specific Docs
- Kubuntu Specific Docs
- Non-Desktop-Specific Docs
- Docs for the Documentation Team

The projects are left unaltered, though I have added the Switching From
Windows guide and the new Contribute to Ubuntu article as projects. It
would be great if all the doc maintainers could update the status of
their docs and alter them so as to fit with a new structure for the Docs
as discussed by Matthews East and Thomas in this thread.

Please add to this and discuss it. My initial reorganization is by no
means set in stone. But I would like the Projects page to clearly
reflect the Docs in the Ubuntu Help as we envision them in Edgy.

- Andreas

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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Duncan Lithgow
In reply to this post by Matthew Paul Thomas-2
I have a very simple request which I think belongs on this thread.

1. Find someone with little tech experience and get them to
help.ubuntu.com
2. Ask them to get find the answer some to unimportant question.
3. Now, notice if they have a clue what HTML means after the name of the
guide.

My suggestion is that prominence be given to the html pages by linking
them with some appropriate text, and that the PDF file be given a lower
visual priority. More people understand that a pdf is a downloadable
file than understand that HTML is the text to click on to read the
online version.

Duncan

--
Linux user: 372812 | GPG key ID: 21A8C63A | http://lithgow-schmidt.dk

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

signature.asc (198 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Help page design, and the future of the Ubuntu Desktop Guide

Corey Burger
On 7/27/06, Duncan Lithgow <[hidden email]> wrote:

> I have a very simple request which I think belongs on this thread.
>
> 1. Find someone with little tech experience and get them to
> help.ubuntu.com
> 2. Ask them to get find the answer some to unimportant question.
> 3. Now, notice if they have a clue what HTML means after the name of the
> guide.
>
> My suggestion is that prominence be given to the html pages by linking
> them with some appropriate text, and that the PDF file be given a lower
> visual priority. More people understand that a pdf is a downloadable
> file than understand that HTML is the text to click on to read the
> online version.
>
> Duncan

I would recommend duplicating the better desktop[2] stuff. If you are
doing user testing, might as well do full blown stuff and actually
record everything.

[1] http://www.betterdesktop.org/blog/

Corey

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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Duncan Lithgow
On Sun, 2006-07-30 at 21:35 -0700, Corey Burger wrote:
> On 7/27/06, Duncan Lithgow <[hidden email]> wrote:
> > I have a very simple request which I think belongs on this thread.
> >
> > 1. Find someone with little tech experience and get them to
> > help.ubuntu.com
> > 2. Ask them to get find the answer some to unimportant question.
> > 3. Now, notice if they have a clue what HTML means after the name of the
> > guide.

https://launchpad.net/distros/ubuntu/+source/ubuntu-docs/+bug/54628
--
Linux user: 372812 | GPG key ID: 21A8C63A | http://lithgow-schmidt.dk

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

signature.asc (198 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Help page design, and the future of the Ubuntu Desktop Guide

Matthew East
In reply to this post by Matthew East
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hiya,

* Matthew East:

> For the next release, what I propose we do is this:
>
>  * Generally speaking, work with the existing guides but bear in mind
> Matthew's comments about how to write good help, and improve the guides
> accordingly.
>  * Eliminate any overlap between the guides, and identify ways to
> present a coherent front page. So, for example, it might include:
>
> Adding, Removing and Updating Software in Ubuntu [1]
> Working with your Desktop [2]
> Working with a Server [3]
> Getting more help [4]
> Contributing to Ubuntu [5]
>
> [1] An article, based on what is currently in the desktop guide
> [2] A book, what is now the desktop guide
> [3] A book, what is now the server guide
> [4] An article, based on what is currently in the desktop guide
> [5] An article, potentially new, which includes a link to the packaging
> guide.

I should have added [0] Introduction to Ubuntu (what is now "About Ubuntu").

Does anyone have any more comments about this for Ubuntu? If not, can we
go ahead and start making it happen?

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEzgDxtSaF0w5rBv8RAlXhAKCA8ueP+EXEa1YR16M1qoRE1Y8hwQCfQJhW
WyLzL9jT8KuDVDrcEWEV/DA=
=Rw9u
-----END PGP SIGNATURE-----


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Jonathan Jesse-2
On Monday 31 July 2006 09:09, Matthew East wrote:

> Hiya,
>
> * Matthew East:
> > For the next release, what I propose we do is this:
> >
> >  * Generally speaking, work with the existing guides but bear in mind
> > Matthew's comments about how to write good help, and improve the guides
> > accordingly.
> >  * Eliminate any overlap between the guides, and identify ways to
> > present a coherent front page. So, for example, it might include:
> >
> > Adding, Removing and Updating Software in Ubuntu [1]
> > Working with your Desktop [2]
> > Working with a Server [3]
> > Getting more help [4]
> > Contributing to Ubuntu [5]
> >
> > [1] An article, based on what is currently in the desktop guide
> > [2] A book, what is now the desktop guide
> > [3] A book, what is now the server guide
> > [4] An article, based on what is currently in the desktop guide
> > [5] An article, potentially new, which includes a link to the packaging
> > guide.
>
> I should have added [0] Introduction to Ubuntu (what is now "About
> Ubuntu").
>
> Does anyone have any more comments about this for Ubuntu? If not, can we
> go ahead and start making it happen?
>
> Matt

I think it is time to get started on this as we on the doc-team have this
nasty habit of talking a lot and discussing everything to the point that doc
freeze will come and nothing will be changed.  Let's get started :)

Jonathan

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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Matthew Paul Thomas-2
In reply to this post by Matthew East
On Aug 1, 2006, at 1:09 AM, Matthew East wrote:

> ...
> * Matthew East:
>>
>> For the next release, what I propose we do is this:
>>
>>  * Generally speaking, work with the existing guides but bear in mind
>> Matthew's comments about how to write good help, and improve the
>> guides accordingly.
>> ...
> Does anyone have any more comments about this for Ubuntu? If not, can
> we go ahead and start making it happen?
> ...

I haven't seen anyone address my original question yet. :-) That is,
what should be done with the printed version of the Ubuntu Desktop
Guide?
>
> (1) Fork it from the on-screen version, so that it can be given proper
>     book treatment (chapters, footnotes, screenshots, diagrams, etc).
> (2) Continue it as a quirkier, recipe-book-style, printed copy of every
>     help page, without chapter introductions and the like.
> (3) Retire it, leaving the job of publishing books to Apress, O'Reilly,
>     Canonical and Prentice Hall, Addison-Wesley, etc.
>     <http://urlx.org/amazon.com/d9ea0>

--
Matthew Paul Thomas
http://mpt.net.nz/


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

Re: Help page design, and the future of the Ubuntu Desktop Guide

Matthew East
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

* Matthew Paul Thomas:

> I haven't seen anyone address my original question yet. :-) That is,
> what should be done with the printed version of the Ubuntu Desktop
> Guide?
>> (1) Fork it from the on-screen version, so that it can be given proper
>>     book treatment (chapters, footnotes, screenshots, diagrams, etc).
>> (2) Continue it as a quirkier, recipe-book-style, printed copy of every
>>     help page, without chapter introductions and the like.
>> (3) Retire it, leaving the job of publishing books to Apress, O'Reilly,
>>     Canonical and Prentice Hall, Addison-Wesley, etc.
>>     <http://urlx.org/amazon.com/d9ea0>

If we are going to use ghelp: links to refer to other articles in the
help system, and start integrating some of the upstream manuals into the
body of the desktop guide, I think the answer is to retire books
entirely for now.

Sorry to see it go of course, but there is not enough time before edgy
to work on both a good help system and a good set of books. Maybe in
future releases we can start to work on both.

What do others think?

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFE0d+AtSaF0w5rBv8RAtrxAJsHzkLPDNtOgbx5ieHAg3AQH8srZwCfWuDs
W1rIDaLbYLyBzdQTrUbG5mA=
=W3yI
-----END PGP SIGNATURE-----


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

[PATCH] UDG: Begins book->help pages conversion

Matthew Paul Thomas-2
Matthew East wrote:

> ...
> If we are going to use ghelp: links to refer to other articles in the
> help system, and start integrating some of the upstream manuals into the
> body of the desktop guide, I think the answer is to retire books
> entirely for now.
>
> Sorry to see it go of course, but there is not enough time before edgy
> to work on both a good help system and a good set of books. Maybe in
> future releases we can start to work on both.
> ...
So here's a patch to start the conversion of the Ubuntu Desktop Guide
from a book into a categorized collection of help pages, by removing the
preface. Here's where each part went.
*   "Introduction to the Ubuntu Desktop Guide": Deleted. Redundant with
    the table of contents.
*   "Conventions": Mostly deleted. If the admonition and command-line
    displays aren't obvious, that's a bug to be fixed in Yelp's CSS;
    adding a page explaining them won't work. The parts on menu items
    and keyboard shortcuts are temporarily moved to the "Getting
    Started" section.
*   "Contributing and Feedback": Now in its own "How you can help"
    section. Again, this is temporary, but I think it would be quite
    shippable if I got hit by a bus tomorrow and nobody made further
    changes.

After this I'll go to work on rearranging the "Getting Started" and
"Common Tasks" sections into more useful categories.

Cheers
--
Matthew Paul Thomas
http://mpt.net.nz/

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

diff-udg-no-preface.gz (4K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] UDG: Begins book->help pages conversion

Matthew East
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

* Matthew Paul Thomas:

> Matthew East wrote:
>> ...
>> If we are going to use ghelp: links to refer to other articles in the
>> help system, and start integrating some of the upstream manuals into the
>> body of the desktop guide, I think the answer is to retire books
>> entirely for now.
>>
>> Sorry to see it go of course, but there is not enough time before edgy
>> to work on both a good help system and a good set of books. Maybe in
>> future releases we can start to work on both.
>> ...
>
> So here's a patch to start the conversion of the Ubuntu Desktop Guide
> from a book into a categorized collection of help pages, by removing the
> preface. Here's where each part went.

I've applied the patch and done some changes of my own. The principal
one is removing the "About Ubuntu" section in Getting Started, this is
redundant with the About Ubuntu document on the front page of yelp.

> *   "Contributing and Feedback": Now in its own "How you can help"
>     section. Again, this is temporary, but I think it would be quite
>     shippable if I got hit by a bus tomorrow and nobody made further
>     changes.

I've changed this from a chapter to an appendix (because otherwise the
table of contents was numbered like this: 1, 2, 3, A, B, 4. But it got
me thinking more: do we actually want a chapter in the desktop section
about contributing and feedback? It should be part of the "contribute"
document on the front page of yelp, so maybe we can remove it. The case
for that becomes especially compelling if some kind of feedback
mechanism can be integrated with yelp.

Another thing, those appendices are pretty ugly, do we really need to
reproduce each licence in an appendix like that? How about if we shipped
them with the system as articles and linked to them from the "About this
document" page? I'll take a look to see if this is appropriate legally
speaking. What do people think?

> After this I'll go to work on rearranging the "Getting Started" and
> "Common Tasks" sections into more useful categories.

Do you want to list some ideas you have for useful categories in an
email so that we can discuss them before implementing?

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFE1wSytSaF0w5rBv8RAjkVAJ9hVwkwICJDYAUa0gvNqkQJlTvd4gCePZtz
AR5SUJQjN+ZSYwXTR9R13RQ=
=uWEj
-----END PGP SIGNATURE-----


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

Re: [PATCH] UDG: Begins book->help pages conversion

Andreas Lloyd
Matthew East wrote:

> * Matthew Paul Thomas:
> >> *   "Contributing and Feedback": Now in its own "How you can help"
> >>     section. Again, this is temporary, but I think it would be quite
> >>     shippable if I got hit by a bus tomorrow and nobody made further
> >>     changes.
>
> I've changed this from a chapter to an appendix (because otherwise the
> table of contents was numbered like this: 1, 2, 3, A, B, 4. But it got
> me thinking more: do we actually want a chapter in the desktop section
> about contributing and feedback? It should be part of the "contribute"
> document on the front page of yelp, so maybe we can remove it. The case
> for that becomes especially compelling if some kind of feedback
> mechanism can be integrated with yelp.
I'm sure it would be easy to integrate these pages into the Contribute
doc. Just let me know if I need to cover any extra ground if you decide
to nuke the "How you can help" page. You can still find the current
draft of the Contribute Doc at https://wiki.ubuntu.com/ContributeToUbuntu

I don't know about integrating feedback through Yelp, as that will leave
Khelpcenter out of the loop, so instead I've been in touch with Mikko,
the Summer of Code student who is doing the Wiki2DocBook project to hear
if he could add a function to add links to the bottom of exported pages.
I think he's willing to implement this, though he will require some
reminding. He's idling from time to time on #ubuntu-doc, so if you see
him, give him a reminder to have a look at this. :-)

Cheers,
Andreas

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