...in navigation structure but is present in contents. Is there a reason for this or is it a mistake?! Screenshots for that page are currently in spanish as well.
Jon
On Mon, 2007-04-02 at 12:07 +0100, Jonathan Roberts wrote:
...in navigation structure but is present in contents. Is there a reason for this or is it a mistake?!
Sorry, I don't understand what you mean. Can you point out where this is happening?
Screenshots for that page are currently in spanish as well.
screenshots-- are evil :)
I think those were placeholders, but the situation speaks to the problems of screenshots.
- Karsten
On 11/04/07, Karsten Wade kwade@redhat.com wrote:
On Mon, 2007-04-02 at 12:07 +0100, Jonathan Roberts wrote:
...in navigation structure but is present in contents. Is there a reason for this or is it a mistake?!
Sorry, I don't understand what you mean. Can you point out where this is happening?
I went ahead and fixed it. The problem was that the links at the bottom of each page, to go forward and back, skipped connecting to the internet - but it was present in the contents...does that make any more sense than what I said before!?
Screenshots for that page are currently in spanish as well.
screenshots-- are evil :)
I think those were placeholders, but the situation speaks to the problems of screenshots.
So is the policy to avoid screenshots?! One thing I thought about the DUG, which maybe is better in a different thread, was that the description talks about it being "task orientated" but some of the sections felt a bit thin on the ground in that respect - is this the kind of concept material to be pushed to other docs?!
Jon
On Wed, 2007-04-11 at 21:02 +0100, Jonathan Roberts wrote:
On 11/04/07, Karsten Wade kwade@redhat.com wrote:
On Mon, 2007-04-02 at 12:07 +0100, Jonathan Roberts wrote:
...in navigation structure but is present in contents. Is there a reason for this or is it a mistake?!
Sorry, I don't understand what you mean. Can you point out where this is happening?
I went ahead and fixed it. The problem was that the links at the bottom of each page, to go forward and back, skipped connecting to the internet - but it was present in the contents...does that make any more sense than what I said before!?
Ah, I see. I think those links can be an exception to the rule of "make all links full URLs". The reasons are:
* The navigation construct is Wiki-only; it doesn't get translated into anything meaningful in the XML-side. That is, you can see a table like the table we made, but in DocBook, the navigation is built automagically.
* The links in DocBook need to be <xref>, that is, an internal cross-reference link. Full URLs are translated to <ulink> tags, which are external URI-based and not built automagically.
Screenshots for that page are currently in spanish as well.
screenshots-- are evil :)
I think those were placeholders, but the situation speaks to the problems of screenshots.
So is the policy to avoid screenshots?!
We do have some directions about them:
http://docs.fedoraproject.org/documentation-guide/s1-screenshots.html
I threw this out recently:
http://www.redhat.com/archives/fedora-docs-list/2007-March/msg00161.html
I think they are much more trouble than the are worth. In fact, they are a bit of a PITA. IMO, it's a self-perpetuating problem that people expect screenshots, so we provide them. I also think good writing stands fine without screenshots. And diagrams are definitely different, which any good screenshot can become; they are a PITA, too, but can be worth it.
But this is really just my opinion. I'm not here to say, "Me professional, me say, this best way!" In fact, the best way is what the community of readers wants *and* needs. It is our job to give them what they need, even if they don't know they need it; and to address their wants. I think we must tune our decisions to our Fedora audience, even if I personally don't like it. There is a (constantly shifting) balance here, somewhere.
This is why I've been trying to spark discussion ... and consensus ... on these style decisions. There are standards, there are opinions, and there is the Fedora Content Way. It is the latter that we need to define and stick with. And it shouldn't be just Paul, Patrick, and me making all these decisions -- unless you all want it that way. ;-D
One thing I thought about the DUG, which maybe is better in a different thread, was that the description talks about it being "task orientated" but some of the sections felt a bit thin on the ground in that respect - is this the kind of concept material to be pushed to other docs?!
+1
Yes, this was discussed a bit in some other threads, and is in fact an external complaint we have received. It's all right, that's the way open content goes - you push it out the door, fix bugs, and push it out again.
Mr. Babich -- Maybe we should open the DesktopReferenceGuide? Or a better name? You all can start moving sections around, or each make a copy under e.g. JonathanRoberts/DesktopUserGuide and give a vision of how things could be.
- Karsten
On 4/12/07, Karsten Wade kwade@redhat.com wrote:
<snip>
Mr. Babich -- Maybe we should open the DesktopReferenceGuide? Or a better name? You all can start moving sections around, or each make a copy under e.g. JonathanRoberts/DesktopUserGuide and give a vision of how things could be.
Mr. Wade -- Despite needing a vacation to recover from my vacation :-), I will give it some serious thought. The best title for the comprehensive guide sounds like a good topic for #fedora-docs.
As for the vision, my eyesight's a little cloudy right now. I envision a core of common topics, such as OpenOffice.org and Firefox, with special sections on the particulars of GNOME, KDE, etc. A KDE example would be Konqueror. Of course, the GNOME, KDE and Xfce applications can be run from any window manager (with the required libraries installed).
I'm open to any ideas on the best way to organize the material. Some possibilities are:
1. Separate guides for GNOME and KDE. Xfce will be included if time permits. Obviously, there will be a great amount of overlap among the different guides. I believe these common topics are best handled by "includes" in both the wiki and DocBook versions.
2. A single guide which points out which apps are "native" to which window manager, but emphasizes that they can mix and match apps as desired, again with the required libraries installed.
Either approach should be modular, so that the reader can skip to topics of interest. Hyperlinks in the wiki version are an obvious solution, but do not address the DocBook version. Perhaps a good table of contents is all that is needed.
I agree with the opinion that screenshots are a PITA to maintain. We need to evaluate the benefit vs. the cost in terms of maintaining the guide. It certainly complicates the translation process.
Finally, regarding the Fedora 7 default home page, we need to ensure that the link to the new guide is flexible enough to point the user to the final version for Fedora 7, while we still have a draft version on the wiki on which to work for Fedora 8.
Note: The assumption that the end user does not have root access makes little sense in light of the fact that most users will need to do updates and want to install new applications. Please correct me if I am wrong in this regard.
John Babich Volunteer, Fedora Docs Project
As for the vision, my eyesight's a little cloudy right now. I envision a core of common topics, such as OpenOffice.org and Firefox, with special sections on the particulars of GNOME, KDE, etc. A KDE example would be Konqueror. Of course, the GNOME, KDE and Xfce applications can be run from any window manager (with the required libraries installed).
Would the best place to start be to try and draw up a comprehensive list of topics (or perhaps I should say tasks) that should be covered? Might be interesting to ask on the forums to get users feedback on what are the common tasks they do...
I'm open to any ideas on the best way to organize the material. Some possibilities are:
Separate guides for GNOME and KDE. Xfce will be included if time permits. Obviously, there will be a great amount of overlap among the different guides. I believe these common topics are best handled by "includes" in both the wiki and DocBook versions.
A single guide which points out which apps are "native" to which window manager, but emphasizes that they can mix and match apps as desired, again with the required libraries installed.
I think it's worth considering that the guides may be used by people who might not realise the difference between Gnome and KDE, in which case I think an integrated approach might be better as would help to make this clear.
Jon
On Thu, 2007-04-12 at 09:47 +0100, Jonathan Roberts wrote:
I think it's worth considering that the guides may be used by people who might not realise the difference between Gnome and KDE, in which case I think an integrated approach might be better as would help to make this clear.
I would extend this further to guess that those who aren't aware of the window manager differences use the default (GNOME). So, this actually gives them an introduction to equivalency in KDE.
How about a structure similar to this?
= Task Foo =
== Foo in Default Desktop ==
<GNOME how to foo>
== Foo in KDE Desktop ==
<KDE how to foo>
== Foo in Xfce ==
<Xfce how to foo>
...
This fairly simple structure allows default, don't-want-anything-different users to skim from topic to topic without being "distracted" by the non-default. At the same time, the non-default is given equivalency.
By making all of our tasks stubbed out in this fashion, it makes it easier for a KDE-knowledgeable contributor to know where to fill in the blanks.
- Karsten
On 12/04/07, Karsten Wade kwade@redhat.com wrote:
On Thu, 2007-04-12 at 09:47 +0100, Jonathan Roberts wrote:
I think it's worth considering that the guides may be used by people who might not realise the difference between Gnome and KDE, in which case I think an integrated approach might be better as would help to make this clear.
I would extend this further to guess that those who aren't aware of the window manager differences use the default (GNOME). So, this actually gives them an introduction to equivalency in KDE.
How about a structure similar to this?
= Task Foo =
== Foo in Default Desktop ==
<GNOME how to foo>
== Foo in KDE Desktop ==
<KDE how to foo>
== Foo in Xfce ==
<Xfce how to foo>
Looks like a cool approach to me :D
Jon
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Most end-user can't tell the difference between gnome and kde (at least, not the beginning end user who's reading the DUG) Maybe if it is explained the difference in the introduction it works...
Y.S.
nc Jonathan Roberts escribió:
On 12/04/07, Karsten Wade kwade@redhat.com wrote:
On Thu, 2007-04-12 at 09:47 +0100, Jonathan Roberts wrote:
I think it's worth considering that the guides may be used by people who might not realise the difference between Gnome and KDE, in which case I think an integrated approach might be better as would help to make this clear.
I would extend this further to guess that those who aren't aware of the window manager differences use the default (GNOME). So, this actually gives them an introduction to equivalency in KDE.
How about a structure similar to this?
= Task Foo =
== Foo in Default Desktop ==
<GNOME how to foo>
== Foo in KDE Desktop ==
<KDE how to foo>
== Foo in Xfce ==
<Xfce how to foo>
Looks like a cool approach to me :D
Jon
Karsten Wade wrote:
I would extend this further to guess that those who aren't aware of the window manager differences use the default (GNOME). So, this actually gives them an introduction to equivalency in KDE.
How about a structure similar to this?
= Task Foo =
== Foo in Default Desktop ==
<GNOME how to foo>
== Foo in KDE Desktop ==
<KDE how to foo>
== Foo in Xfce ==
<Xfce how to foo>
Have you considered a person who doesn't know the differences between GNOME, KDE and XFCE? When the person comes across such structure it become mandatory for the person to understand the differences between these desktop environments and what he/she is running at present before following the instructions in the guide.
Separate guides for each of the desktop environments can avoid this issue.
Rahul
On Thu, 2007-04-12 at 23:43 +0530, Rahul Sundaram wrote:
Have you considered a person who doesn't know the differences between GNOME, KDE and XFCE? When the person comes across such structure it become mandatory for the person to understand the differences between these desktop environments and what he/she is running at present before following the instructions in the guide.
Separate guides for each of the desktop environments can avoid this issue.
By doing this, you move the need to understand the differences between GNOME, KDE, and XFCE outside of the guide and onto the docs page.
The all-one-guide approach:
"Fedora New User Guide - How to do your common tasks in Fedora, focused on users who are new to Fedora and/or Linux in general."
The many-guides approach:
"Fedora New GNOME User Guide - How to do your common tasks in Fedora, focused on users who are new to Fedora and/or Linux in general and who are using the GNOME desktop environment."
"Fedora New KDE User Guide - How to do your common tasks in Fedora, focused on users who are new to Fedora and/or Linux in general and who are using the KDE desktop environment."
"Fedora New XFCE User Guide - How to do your common tasks in Fedora, focused on users who are new to Fedora and/or Linux in general and who are using the XFCE desktop environment."
"Note: Fedora offers three choices of desktop environment, with GNOME being the default. While you can install and run applications from any desktop environment, you may choose to have the interface specifically use the engines and tools provided in GNOME, KDE, or XFCE."
OK, then we have to link to what all the new special terms mean ... etc.
Another negative, three separate guides that have X% identical content and Y% unique content, maintained on a Wiki. In DocBook, it would be easier. You would have one guide to maintain and three make targets.
If we're not going to teach about the differences between the desktop environments ... then why write about them in the first place?
- Karsten
Karsten Wade wrote:
If we're not going to teach about the differences between the desktop environments ... then why write about them in the first place?
Good question. The difference between these approaches to me is that when I know that users are using GNOME I can just point them to the specific guide and not worry about them getting confused over the different desktop environments.
Maybe that is not a big advantage but it is worth considering.
Rahul
On Fri, 2007-04-13 at 00:17 +0530, Rahul Sundaram wrote:
Karsten Wade wrote:
If we're not going to teach about the differences between the desktop environments ... then why write about them in the first place?
Good question. The difference between these approaches to me is that when I know that users are using GNOME I can just point them to the specific guide and not worry about them getting confused over the different desktop environments.
Maybe that is not a big advantage but it is worth considering.
XSLT would help us over come this, so we authors could write the documents as a unified whole, right? The first chapter could include a "How to identify your desktop" bit. Each task could have a mini-ToC pointing to the each of the 2+ sets of instructions. Mind you, I don't quite know how to accomplish this, but I'm confident it's possible.
On Thu, 2007-04-12 at 19:20 -0400, Paul W. Frields wrote:
XSLT would help us over come this, so we authors could write the documents as a unified whole, right? The first chapter could include a "How to identify your desktop" bit. Each task could have a mini-ToC pointing to the each of the 2+ sets of instructions. Mind you, I don't quite know how to accomplish this, but I'm confident it's possible.
That's back to the mechanics. Yes, *if* we were writing natively in XML, *then* it would be easier to do a three-way output. Easier than a Wiki. Not easier than a one-way output from a well-integrated outline.
But we are not writing natively in XML. To do this, we would need to duplicate the current Wiki structure, Include() like crazy, keep it all together ... then stitch it into the three-way output from XML approach.
Someone can correct me if I'm wrong, but it's frankly too late in the release cycle to consider taking the "longer and possibly more rewarding approach", especially when the reward is so murky.
Rahul - try this: "You are using the default install, right? Then refer to the Fedora New Users Guide for GNOME ..." You're going to be checking that the install is default, anyway.
We're producing the KDE et al versions because people said it was important to them. Of course, none of those people have shown up to do the actual work, but they sure seem to show up to complain about it ...
I'm sure there are users who love KDE and want to see this DUG version happen; if we can create the structure for them to see and possibly work from, maybe we can attract their interest in working on it.
- Karsten
On Fri, 2007-04-13 at 07:34 -0700, Karsten Wade wrote:
On Thu, 2007-04-12 at 19:20 -0400, Paul W. Frields wrote:
XSLT would help us over come this, so we authors could write the documents as a unified whole, right? The first chapter could include a "How to identify your desktop" bit. Each task could have a mini-ToC pointing to the each of the 2+ sets of instructions. Mind you, I don't quite know how to accomplish this, but I'm confident it's possible.
That's back to the mechanics. Yes, *if* we were writing natively in XML, *then* it would be easier to do a three-way output. Easier than a Wiki. Not easier than a one-way output from a well-integrated outline.
But we are not writing natively in XML. To do this, we would need to duplicate the current Wiki structure, Include() like crazy, keep it all together ... then stitch it into the three-way output from XML approach.
Someone can correct me if I'm wrong, but it's frankly too late in the release cycle to consider taking the "longer and possibly more rewarding approach", especially when the reward is so murky.
No, you're absolutely right. I end up being a little tunnel-vision when it comes to writing mechanics.
Rahul - try this: "You are using the default install, right? Then refer to the Fedora New Users Guide for GNOME ..." You're going to be checking that the install is default, anyway.
We're producing the KDE et al versions because people said it was important to them. Of course, none of those people have shown up to do the actual work, but they sure seem to show up to complain about it ...
I'm sure there are users who love KDE and want to see this DUG version happen; if we can create the structure for them to see and possibly work from, maybe we can attract their interest in working on it.
+1. New folks, this call is for you! Roll up your sleeves and start working. Use this list to get organized when necessary, but use the wiki for working.
I would caution folks to avoid duplicating the material that's already available from your desktop. For instance, if I hit F1 on my GNOME desktop, the "yelp" Help Browser appears. On the front page appears a prominent link to the official GNOME Desktop User Guide. I'm certain a similar function is available in KDE. Anything we do in a New Users Guide should build on that, not duplicate it or supersede it (unless our usage differs from what's in the upstream DUG). I think I said this before at some point, but a lot of new people have {dis,}appeared since then.
+1. New folks, this call is for you! Roll up your sleeves and start working. Use this list to get organized when necessary, but use the wiki for working.
I would caution folks to avoid duplicating the material that's already available from your desktop. For instance, if I hit F1 on my GNOME desktop, the "yelp" Help Browser appears. On the front page appears a prominent link to the official GNOME Desktop User Guide. I'm certain a similar function is available in KDE. Anything we do in a New Users Guide should build on that, not duplicate it or supersede it (unless our usage differs from what's in the upstream DUG). I think I said this before at some point, but a lot of new people have {dis,}appeared since then.
Could you clear up exactly what the plan is here? As I understand it you would like an attempt at a restructured DUG, possibly with new information, which is more task orientated...created under a page like JonathanRoberts/DUG as a draft. (My name was only an example here!)
I'm happy to do some work on this and get the ball rolling but want to make sure this is what people had in mind and not just KDE specific work.
Yours kindly,
Jon
On Thu, 2007-04-12 at 11:30 +0300, John Babich wrote:
- Separate guides for GNOME and KDE. Xfce will be included if time permits. Obviously, there will be a great amount of overlap among the different guides. I believe these common topics are best handled by "includes" in both the wiki and DocBook versions.
+1
- A single guide which points out which apps are "native" to which window manager, but emphasizes that they can mix and match apps as desired, again with the required libraries installed.
Hmm, this is getting a little too jargon-y for the stated audience, methinks. Remember the DUG is for Grandma.
[...snip...]
Finally, regarding the Fedora 7 default home page, we need to ensure that the link to the new guide is flexible enough to point the user to the final version for Fedora 7, while we still have a draft version on the wiki on which to work for Fedora 8.
Note: The assumption that the end user does not have root access makes little sense in light of the fact that most users will need to do updates and want to install new applications. Please correct me if I am wrong in this regard.
The topic of software updates and installation, though, is not something the DUG should cover, so the assumption doesn't hurt in this case. That's likely for the System Administration Guide. The DUG can easily contain a pointer to that resource of course.
-
John Babich -
Jonathan Roberts -
Karsten Wade -
Nicolas A. Corrarello -
Paul W. Frields -
Rahul Sundaram