Created attachment 80786 [details] [review]
patch on goscustdesk.xml

Here's a start. It's subject to two limitations:

1. I am working from the version of Gnome Control Center in Ubuntu Feisty at the moment, and I guess (and hope) that there will be some further rationalising of the category structure before 2.18 is released - some of it is downright crazy.

2. There were a couple of sections which I couldn't find in my system, either they have been merged with other preferences or simply excluded from the menu in Ubuntu, I don't know. I've left these as top level sections and prefixed the title with the # symbol so you can see them easily in Yelp when trying the patch.

Created attachment 80813 [details] [review]
new patch on user-guide/C

Here's an updated patch following some conversations with control-center maintainers about the categorisation and structure.

Some notes:

1. I think we should remove "Preferences" from the title of each section.
2. CD Database Preferences - isn't in preferences list anymore, it's accessed from the programs  - can we delete this section or does this need to be made accessible from elsewhere?
3. File Management Preferences - isn't in preferences list anymore, it's accessed directly from nautilus, so I've removed it.
4. A number of capplets aren't documented, as follows:
  * Hardware - Removable Drives and Media, PalmOS, Printing
  * Internet and Network - Network, Shared Folders, Network Tools
  * Personal - About Me (ex Login Photo?),  keyring manager
  * System - Keyboard Indicator Plugins, Login Window, Power Management, Services, System Log, System Monitor, Time and Date, Users and Groups

Some (e.g. Printing) may have documentation elsewhere in the guide. Can these be moved?

Matt

1. I tried it, and you get sections with funny titles like 'Windows'. That could be confused with other sections of the User Guide. Also, it makes xref links look funny too.
2. Which programs? Which of them are stock Gnome?
3. Ok. But any ids of sections you remove have to be preserved as anchors in case someone somewhere is linking to them... I've moved these to the Nautilus prefs section in the Nautilus chapter. That's the only section you've outright removed?
4. Some of those are known to be missing entirely... patches welcome as always.
   Some of those are under the impression they are apps in their own right, and might have documentation elsewhere in CVS (eg Time Administration Tool Manual). This should be moved into the UG. Same conditions apply ;)
   Some as you say are elsewhere in the UG. Yes, they should be moved.

Some downsides with the patch:

- Font Preferences now doesn't split, which makes it a very long page with no indication of what to find further down. Admittedly, there are at least a couple of procedure-based sections there eg 'Previewing a Font' which maybe belong elsewhere... but where?
- The same goes for Theme.
- Um, same with Mouse preferences, and in this case nothing can be moved out as the subsections describe each tab. 

I could change the chunk depth, but that acts on the whole UG and other bits, eg 7.4. Yelp Help Browser will go a bit weird and microsectionish. Any thoughts on this?

Anyway, applying the patch but there's a few issues still to be cleared up so leaving open.

(In reply to comment #3)
> 1. I tried it, and you get sections with funny titles like 'Windows'. That
> could be confused with other sections of the User Guide. Also, it makes xref
> links look funny too.

Well, not really. The titles of the programs don't have "Preferences" in. I don't think the xref links look funny at all: it's much more confusing to have the sections of the guide different to the titles in the Control-Center.

> 2. Which programs? Which of them are stock Gnome?

I don't know. I looked in Rhythmbox, Totem and Sound-Juicer and it isn't in any of those, AFAICS. But the maintainers will know more.

> 3. Ok. But any ids of sections you remove have to be preserved as anchors in
> case someone somewhere is linking to them... I've moved these to the Nautilus
> prefs section in the Nautilus chapter. That's the only section you've outright
> removed?

Yes, thanks.

> 4. Some of those are known to be missing entirely... patches welcome as always.
>    Some of those are under the impression they are apps in their own right, and
> might have documentation elsewhere in CVS (eg Time Administration Tool Manual).
> This should be moved into the UG. Same conditions apply ;)
>    Some as you say are elsewhere in the UG. Yes, they should be moved.

If you can give me any further details about which is which, then I'll appreciate it! Otherwise I shall poke around.

> Some downsides with the patch:
> 
> - Font Preferences now doesn't split, which makes it a very long page with no
> indication of what to find further down. Admittedly, there are at least a
> couple of procedure-based sections there eg 'Previewing a Font' which maybe
> belong elsewhere... but where?
> - The same goes for Theme.
> - Um, same with Mouse preferences, and in this case nothing can be moved out as
> the subsections describe each tab. 
> 
> I could change the chunk depth, but that acts on the whole UG and other bits,
> eg 7.4. Yelp Help Browser will go a bit weird and microsectionish. Any
> thoughts on this?

I would change the chunk depth, and delete the Yelp Help Browser section (help on a help system?). But if you're not into that, we can appeal to the developers to implement a means to change the chunk depth on a chapter by chapter basis.

Thanks for your comments.

Matt

(In reply to comment #4)
> > 1.
> Well, not really. The titles of the programs don't have "Preferences" in. I
> don't think the xref links look funny at all: it's much more confusing to have
> the sections of the guide different to the titles in the Control-Center.

The xref links end up in sentences like:
'For more on setting a left-handed mouse, see Section x.x.x, "Mouse".'
Reading that in a section that is itself called something like 'Using the mouse' seems very odd to me.

> > 2. Which programs? Which of them are stock Gnome?
> 
> I don't know. I looked in Rhythmbox, Totem and Sound-Juicer and it isn't in any
> of those, AFAICS. But the maintainers will know more.

I'll remove the section. It would be nice to give it a home, but if nobody wants it...

> > 4.
> If you can give me any further details about which is which, then I'll
> appreciate it! Otherwise I shall poke around.

I would try launching each tool and seeing if it has a help button. If it does, and it works, then it's off to the repository for a hunt, as heaven forfend thesse things all live in one module.
Beyond that, your guess is as good as mine!

> I would change the chunk depth, and delete the Yelp Help Browser section (help
> on a help system?). 

Help on Yelp was added last cycle because there are a few undocumented feature of Yelp. Shaun insisted it not be a separate Help manual, so was been tossed into the maw of the UG.

> But if you're not into that, we can appeal to the
> developers to implement a means to change the chunk depth on a chapter by
> chapter basis.

I filed bug 352700 on that a while ago, but feel free to appeal too :)

(In reply to comment #5)
> (In reply to comment #4)
> > > 1.
> > Well, not really. The titles of the programs don't have "Preferences" in. I
> > don't think the xref links look funny at all: it's much more confusing to have
> > the sections of the guide different to the titles in the Control-Center.
> 
> The xref links end up in sentences like:
> 'For more on setting a left-handed mouse, see Section x.x.x, "Mouse".'
> Reading that in a section that is itself called something like 'Using the
> mouse' seems very odd to me.

Alright. (Maybe it would be better for the link to say "see Configuring Your Desktop/Hardware/Mouse")

> > > 2. Which programs? Which of them are stock Gnome?
> > 
> > I don't know. I looked in Rhythmbox, Totem and Sound-Juicer and it isn't in any
> > of those, AFAICS. But the maintainers will know more.
> 
> I'll remove the section. It would be nice to give it a home, but if nobody
> wants it...

Ok thanks.

> > > 4.
> > If you can give me any further details about which is which, then I'll
> > appreciate it! Otherwise I shall poke around.
> 
> I would try launching each tool and seeing if it has a help button. If it does,
> and it works, then it's off to the repository for a hunt, as heaven forfend
> thesse things all live in one module.
> Beyond that, your guess is as good as mine!

Thanks, will try it.

> > I would change the chunk depth, and delete the Yelp Help Browser section (help
> > on a help system?). 
> 
> Help on Yelp was added last cycle because there are a few undocumented feature
> of Yelp. Shaun insisted it not be a separate Help manual, so was been tossed
> into the maw of the UG.

None of em are useful for users though, maybe some of them are useful for documentation writers! :) Anyway, the Tools and Utilities section is a bit mysterious, tbh.

> > But if you're not into that, we can appeal to the
> > developers to implement a means to change the chunk depth on a chapter by
> > chapter basis.
> 
> I filed bug 352700 on that a while ago, but feel free to appeal too :)


Will do.

(In reply to comment #5)
> (In reply to comment #4)
> > > 1.
> > Well, not really. The titles of the programs don't have "Preferences" in. I
> > don't think the xref links look funny at all: it's much more confusing to have
> > the sections of the guide different to the titles in the Control-Center.
> 
> The xref links end up in sentences like:
> 'For more on setting a left-handed mouse, see Section x.x.x, "Mouse".'
> Reading that in a section that is itself called something like 'Using the
> mouse' seems very odd to me.

Actually, I've had another thought on this.

Since this section now doesn't deal any longer simply with "preferences", and the word doesn't appear anywhere, I think we can replace it with more helpful titles.

For example, I'd like to move the Printing section into "Hardware", and it's entitled "Setting up a Printer", which is a nice task-based title. If we changed the Mouse title to "Configuring a Mouse", that would solve your xref issue; and at the same time get a nice coherence about dealing with both preferences and administrative tools together.

I'll do another patch if you think it's a good idea.

Should I open separate bugs for new patches? For example, if I want to do one to move the Printing section as described above?

(In reply to comment #5)
> (In reply to comment #4)
> > But if you're not into that, we can appeal to the
> > developers to implement a means to change the chunk depth on a chapter by
> > chapter basis.
> 
> I filed bug 352700 on that a while ago, but feel free to appeal too :)

FYI, I discovered something quite cool - you can add a chunk depth to each chapter, and it works if yelp is opening the chapter as a standalone document (which is what Ubuntu is hoping to do with the Customising Your Desktop chapter).

For example, http://www.mdke.org/tmp/chunk-magic.png

Created attachment 80952 [details] [review]
mdke3.patch

Ok, here's another patch which:

1. corrects the reference to System->Preferences/Administration wherever I happened to see it.
2. Adds extra chunking to goscustdesk.xml for those viewing it as a standalone chapter.
3. Merges the network-admin documentation, as discussed with maintainer on bug 399602. NOTE: if the patch gets accepted, the translations will need to be merged too, I'll contact the list about that. FURTHER NOTE: you need to add http://mdke.org/tmp/network-tool.png to C/figures manually, I can't include that in the patch obviously.
4. Deletes the CDDB Database section (I'm confirming with the gnome-media maintainers that we can scrap this).
5. Moves the Printing section from Tools & Utilities into Configuring Your Desktop.
6. Adds me and Carlos to contributors section (please advise as to whether this is correct practice).

Sorry for doing so many things at once, but when one gets the fervour, it's hard to go slowly.

(In reply to comment #6)
> Alright. (Maybe it would be better for the link to say "see Configuring Your
> Desktop/Hardware/Mouse")

A fair amount of that text is generated by Yelp when it sees the xref element. Everything after 'see', in fact.

> None of em are useful for users though, maybe some of them are useful for
> documentation writers! :) Anyway, the Tools and Utilities section is a bit
> mysterious, tbh.

Yeah, 'Tools and Utilities' is another phrase for 'things we don't know where to put, so they're lumped in here'.
There's a few things in there that power users may like to know, eg command line stuff. If you have thoughts on what to do with the Yelp manual or where to move it, file a separate bug, but as Shaun is largely AWOL (due to recent wedding), it won't get dealt with for a while.

(In reply to comment #7)
> Since this section now doesn't deal any longer simply with "preferences", and
> the word doesn't appear anywhere, I think we can replace it with more helpful
> titles.
> 
> For example, I'd like to move the Printing section into "Hardware", and it's
> entitled "Setting up a Printer", which is a nice task-based title. If we
> changed the Mouse title to "Configuring a Mouse", that would solve your xref
> issue; and at the same time get a nice coherence about dealing with both
> preferences and administrative tools together.

That's starting to get pretty complicated.
What we have at the moment in this chapter is mostly interface-based sections. 
We need more task-based stuff, but having both mixed in together seems messy... or is that just me? Maybe it's because the way Yelp works at the moment, which will produce a very crammed table of contents that's hard to scan, like parts of the file manager help.
We'd still need one page central page for each preftool that describes the UI and links to related tasks -- though as that probably won't get linked to as much, you're right, it can be named to match the preftool title.

I can think of several ways to do it:

1. Split into two chapters: "Control Center" for the UI, 1-to-1 sections for each preftool, and "Configuring your Desktop" for tasks. Not very good.

2. Add the task section into each preftool as subsections:
 + Configuring
  + Hardware
   + Mouse
    + Mouse for lefties
Too deep maybe. Also, Yelp lists subsections at the top of the parent, which usually looks odd when you try to do this sort of thing, because we'll get a list of task links with no introduction.

3. Add a Tasks section for each category section:
 + Configuring
  + Hardware
   + Mouse
   + (other pref tools)
   + Tasks
    + Mouse for lefties
    + (Other hardware tasks)
Not sure about this one either -- will people look in a section called something as vague as 'Tasks'? Is Yelp search good enough that people will find it anyway?

I'm tempted to say 'arg it's too complicated', but it's already upon us -- I've been ignoring the 'Adding fonts' sections for too long and you're importing a whole load of task-based stuff. So let's do it. :) I'm open to suggestions on how to organize it, as none of mine are much good.
We might want to take it to another bug once we're done importing though, just so it's easier for others to follow the discussion.

Thanks for the patch. Here's hoping your enthusiasm is contagious!
I don't know when I'll have time to properly go through it and apply it. Thursday at the latest, sooner I hope.

> 6. Adds me and Carlos to contributors section (please advise as to whether this is correct practice).

No idea. DocBook's contributors and copyright confuses me, as do the GFDL requirements. But it seems like the right thing to do.

(In reply to comment #10)
> (In reply to comment #6)
> > Alright. (Maybe it would be better for the link to say "see Configuring Your
> > Desktop/Hardware/Mouse")
> A fair amount of that text is generated by Yelp when it sees the xref element.
> Everything after 'see', in fact.

I notice that in other sections you've used the <link linkend> tag to avoid this unsatisfactory behaviour ;) But yes, it should be fixed in gnome-doc-utils.


> (In reply to comment #7)
> > Since this section now doesn't deal any longer simply with "preferences", and
> > the word doesn't appear anywhere, I think we can replace it with more helpful
> > titles.
> > 
> > For example, I'd like to move the Printing section into "Hardware", and it's
> > entitled "Setting up a Printer", which is a nice task-based title. If we
> > changed the Mouse title to "Configuring a Mouse", that would solve your xref
> > issue; and at the same time get a nice coherence about dealing with both
> > preferences and administrative tools together.
> That's starting to get pretty complicated.
> What we have at the moment in this chapter is mostly interface-based sections. 
> We need more task-based stuff, but having both mixed in together seems messy...

{snip}

> I'm tempted to say 'arg it's too complicated', but it's already upon us -- I've
> been ignoring the 'Adding fonts' sections for too long and you're importing a
> whole load of task-based stuff. So let's do it. :) I'm open to suggestions on
> how to organize it

To be honest, I agree that this is too complicated. For this release, until we have some Mallardy action, we should stick to the interface based approach. In fact, by moving the Printing section into custdesk.xml, I haven't moved away from that approach - the printing utility appears in Control Center too, under Hardware.

Let's keep it simple - our target can be an entry in custdesk.xml for every item that appears in Control Center, using the sections that Control Center uses to give the chapter structure. That doesn't stop us removing the word "preferences" from the section titles though and giving them task based names based on what the capplet does.

> Thanks for the patch. Here's hoping your enthusiasm is contagious!
> I don't know when I'll have time to properly go through it and apply it.
> Thursday at the latest, sooner I hope.

That's great, thanks!

Matt

Good catch on all the instances of the old menu system.
However, could you restore the term 'preference tool' please? It's in the style guide as the correct term for the things you launch from the control center (sorry, no URL link as the style guide is down since we moved to SVN).

I'm not sure about a halfway house with some sections with task-based titles and some not. It'll just look a bit messy. Anyway, we're figuring that out on IRC, so the titles can be changed in a later patch.

Also, is 'Network Settings' still called that? There seems to be a discrepancy with the menu item name, which is 'Networking'. And 'Settings' is superfluous in any case... though that's a bug with the UI not with the help.

What does '\ No newline at end of file' mean at line 449 of the patch?

Created attachment 81025 [details] [review]
updated patch

Ok, this patch addresses those issues. I wasn't able to eliminate the weird no newline thing, must be some bug in one of the programs used to make the patch, but it doesn't affect the validity of the file.

Are you sure about "preference tools"? I've restored it, but I have to say I'm still pretty convinced by the reason that I changed it in the first place: the fact that the Control Center contains all the administrative tools too, which act on a system wide basis, rather than customising user preferences.

As for title entries, as discussed on irc should work (using <titleabbrev>), but I won't do those yet until this patch is committed.

The term "preference tool" doesn't presuppose it's the user's preferences over the system-wide ones.
On OS X, the control panel is called "System Preferences". Everything affects the system anyway.

Patch applied.
Few things I've changed:

- wording about the panel menubar. It bugs me that there's no decent language for a pretty essential part of the Gnome UI. For now it's 'panel menubar'. There's a bug open somewhere for it -- two in fact, one to get a name into the UI.
- rewrote the intro to the prefs section a bit more.
- You forgot to change the menu stuff in the Printers section ;)

I wouldn't mind some sort of explanation to follow '<note><para>Some tools require administrator access.</para></note>', but I personally can't make head nor tail of why some prefs need a password and some not.

(In reply to comment #14)
> Patch applied.

Thanks!

> I wouldn't mind some sort of explanation to follow '<note><para>Some tools
> require administrator access.</para></note>', but I personally can't make head
> nor tail of why some prefs need a password and some not.


"Some tools let you modify essential parts of your system, and therefore require administrative access."

Copied the wording from the gksudo dialogue in Ubuntu.

Ah, nearly forgot - Joachim, you need to add the png file too.

Whoops. Forgot about the png file :(
Though in fact, as no other preference tool shows a screenshot, I'd be in favour of scrapping the image for Network Settings, and also (maybe later) rewriting it so it's in the same structure and style as the other sections. At the moment, it follows the structure for an application which is a bit heavy.

(In reply to comment #15)
> "Some tools let you modify essential parts of your system, and therefore
> require administrative access."
> 
> Copied the wording from the gksudo dialogue in Ubuntu.

Ok if I add that text to the UG?

(In reply to comment #17)
> Whoops. Forgot about the png file :(
> Though in fact, as no other preference tool shows a screenshot, I'd be in
> favour of scrapping the image for Network Settings, and also (maybe later)
> rewriting it so it's in the same structure and style as the other sections. At
> the moment, it follows the structure for an application which is a bit heavy.

Yes, that's true. I think it has too many titles :)

> (In reply to comment #15)
> > "Some tools let you modify essential parts of your system, and therefore
> > require administrative access."
> > 
> > Copied the wording from the gksudo dialogue in Ubuntu.
> 
> Ok if I add that text to the UG?

Sure, of course.

Matt

I've added the gksudo text.

(In reply to comment #18)
> > At
> > the moment, it follows the structure for an application which is a bit heavy.
> 
> Yes, that's true. I think it has too many titles :)

It's also a perfect example of task-based help gone too far!
Eg: 'To save your current network configuration as a "Location"' -- yes, lovely. But what's a 'location'? What does it do? Why might I want one? etc etc... (I'm being rhetorical here; I might copy bits of this to the wiki as examples: http://live.gnome.org/ProjectMallard/DocumentationStyle)

I'm closing this -- some tasks remain, such as rewriting the Network Settings section, adding sections for tools not yet covered, but I'd rather do these on fresh bug reports.

I've reverted part of this as Bug 416039.
Kept the categories as they improve clarity (and it saves a heap of work we'll only have to revert AGAIN next cycle).