Re: A New Look at How We Write Content for the Desktop User Guide
by A. Mani
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
"Karsten 'quaid' Wade" wrote:
>
> Agreed that there is a need for computer education for people without
> experience using computers, but are we sure that Fedora wants to work on
> that problem?
Certainly it should. ..We want a bigger user-base.
> I think I'd rather see some common, upstream documentation that handles
> that, such as from GNOME and KDE. Then we can build from that as a
> base.
Neither of them can possibly handle distro-specific features in a
reasonable way.
More directions will only mean faster adoption and a more stable user-base.
>> 1. New user does not learn about the name of the Add/Remove Software
>> program. The first occurrence of "Add/Remove Software program" can be
>> replaced by "Add/Remove Software program (called 'Pirut')".
>
> How do they not learn about it? Sorry, I'm not getting the initial
> point.
I think it is better if we tell the user about the underlying program
at some point.
The main reason is that, users can resolve simple issues with the
ability to launch a program from the CLI.
> In Fedora 9 and beyond, it is now PackageKit, and the main way to get it
> is through the same '''Add/Remove Software''' launcher. Because that is
> setup to be a sort of alias or abstraction layer, I wonder if we want to
> bother naming the application that currently runs underneath it?
To call it "Add/Remove Programs" in a GUI is certainly 'being
user-friendly'. In user guides at least, it is a good idea to speak
about the underlying program.
> For handling software updates in the Fedora 9 version of the User Guide,
> it sounds like a good idea to keep Pirut/Pup documentation. Note they
> are a useful alternative that may have more features than came in the
> initial PackageKit implementation.
...and with a direct GUI link. That is, instead of the usual
"Launcher--> Help -->...", we can have two menu items off "Add/Remove
Program ".
>> 2. 'kicker' is the whole of the main panel. "Fedora icon in the lower
>> left corner called the Kicker" is just wrong.
>
> I've never heard of any of that before. Is there a canonical reference?
In kde3.*, "kicker" is the whole of the main panel and a command as well.
It is 'Plasma' in kde4.*. Apart from the usual KDE documentation, you can see
http://en.wikipedia.org/wiki/Kicker_(KDE)
Best
A. Mani
--
A. Mani
Member, Cal. Math. Soc
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: http://getfiregpg.org
iD8DBQFI7NaUoIK4BlImohYRAubhAJ9wQGTVUugG9sBf3wb2WygT4fA99QCcD7bL
h5ekdwF278cKImr5IaVQNWQ=
=cjyg
-----END PGP SIGNATURE-----
15 years, 7 months
Re: fedora-wiki-list?
by Kam Salisbury
+1 wiki topics can stand on their own in a seperate list.
--
Kam
http://kamsalisbury.com
GPG key: FAF1751E
-----Original Message-----
From: "Karsten 'quaid' Wade" <kwade(a)redhat.com>
Subj: fedora-wiki-list?
Date: Tue Oct 7, 2008 9:08 pm
Size: 911 bytes
To: fedora-docs-list(a)redhat.com
Nigel proposed today that we form a separate list for wiki-focused
discussions.
Much as I hate promoting list proliferation, these reasons make sense:
* Cross-section of many Fedora groups that could use a low(er) volume,
wiki-only list for: guidelines; usage; new tools; tips; wiki-specific
decisions that affect all projects; etc.
* These same people (packagers, artists, translators, coders,
ambassadors, etc.) don't want nor need to be subscribed to
fedora-docs-list to get this information.
* Especially as we talk about multi-lingual wikis and the complexity
increases, we could use a stand-alone list for discussion.
Thoughts?
+1 or -1 or 0?
cheers - Karsten
--
Karsten Wade, Community Gardener
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41
--- attachment signature.asc ---
--- attachment noname 2.txt ---
--- message truncated ---
15 years, 7 months
Re: prompts in command examples
by Kam Salisbury
With Fedora-live sudo does not work as expected either. It leads to additonal confusion.
--
Kam
http://kamsalisbury.com
GPG key: FAF1751E
-----Original Message-----
From: Jason Taylor <jmtaylor90(a)gmail.com>
Subj: Re: prompts in command examples
Date: Sat Oct 4, 2008 6:29 pm
Size: 1K
To: For participants of the Documentation Project <fedora-docs-list(a)redhat.com>
On Fri, 2008-10-03 at 08:20 +1000, Murray McAllister wrote:
> On Fri, Oct 3, 2008 at 2:32 AM, Karsten 'quaid' Wade <kwade(a)redhat.com> wrote:
> >
> > On Wed, 2008-10-01 at 22:32 -0400, Paul W. Frields wrote:
> >
> >> Note that the su command removes the need for the user to look for
> >> niggling prompt details. It also clarifies that the user should
> >> expect a prompt for the root password.
> >
> > In part of that discussion with the Content Services team, we discussed
> > the need for sudo to be enabled by default. One person was in favor of
> > having each document specify how to enable sudo, but I don't like that
> > rat hole. That is another point we could discuss, however, if any
> > Anonymous Cowards are interested in fixing the common usage. Meanwhile,
> > I'm advocating for a sane sudo-by-default in future Fedora versions so
> > we can stop having to use 'su -c'.
> >
> > - Karsten
>
> I leave this out. I have text preceding the command saying "Run the
> following command as the Linux root user:", because I'm too lazy to
> decide between sudo or su ;)
I agree that a standard for documentation purposes of using 'su -c' or
'sudo' is a good thing. On a tangent, however, I have noticed with sudo
that it doesn't always find the command that the user is trying to run.
For example, try and run restorecon as sudo. It doesn't work
out-of-the-box at least for me anyway.
-Jason
--- attachment signature.asc ---
--- attachment noname 2.txt ---
--- message truncated ---
15 years, 7 months
publishing documentation in Fedora
by Murray McAllister
Hi,
Two questions:
1. Is there any documentation on the procedure for having
documentation published in Fedora, for example, hosted on
<http://docs.fedoraproject.org/>?
2. To get documentation in there, do I have to use the fedora-docs
toolchain to make the RPMs?
Cheers.
15 years, 7 months
Self-Introduction: A. Mani
by A. Mani
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello All,
My name is A. Mani. I am a Mathematician and a logician.
My research interests are in Algebra, Partial Algebra, Logic, Rough
Sets and Foundations of Mathematics.
I am good in specifications, formal specifications, R, Prolog, Scheme, LaTeX and
scientific computing too. This has led to a few part-time projects
during the last few years.
I have been involved in FLOSS and OSS promotion for over six years
and see a very bright future for the Fedora project. I coordinate the
activities of ILUG-CALINFO
(www.ilug-cal.info) and am active at LQ too.
I would like to improve existing documentation and contribute to
specialized sections.
My wiki page is at https://fedoraproject.org/wiki/User:amani
My homepage is at http://amani.topcities.com
I am a Fedora Ambassador too.
Best
A. Mani
- --
A. Mani
Member, Cal. Math. Soc
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: http://getfiregpg.org
iD8DBQFI6quRoIK4BlImohYRArtNAKCX2lLNfVOKra4ndTNZpUcxsBQQQQCfZpQ8
TLc86bdxV2c6NWqGgJ7ZzYc=
=7zQn
-----END PGP SIGNATURE-----
15 years, 7 months
prompts in command examples
by Murray McAllister
Hi,
The Red Hat documentation team recently had a discussion about using
prompts (such as "$" and "#") in command examples.
Joshua "top-posting ftw" Wulf came up with the following, and everyone
agreed (I think...):
---
OK, here it is:
When it's a command that should (could) be cut and pasted, it should
have no prompt. Example:
ls -Z /tmp
When it's a record of an interactive session then the prompt should be
included to distinguish commands from output. Example:
# ls -Z /tmp
-rw-rw-r-- auser auser user_u:object_r:user_home_t bar
-rw-rw-r-- auser auser user_u:object_r:user_home_t foo
And when you want to make some commentary on that, you close the box
and then speak.
---
Does anyone have any suggestions or objections?
Cheers.
15 years, 7 months
Re: A New Look at How We Write Content for the Desktop User Guide
by Kam Salisbury
Hi Elizabeth! Thanks for your comments. Hopefully I will be able to meet your expectations in documentation I am a part of in the future. (I am a new documentation contributor)
You are welcome to contact me with feedback or commentary on any documentation at this point forward.
--
Kam
http://kamsalisbury.com
GPG key: FAF1751E
-----Original Message-----
From: Elizabeth Ann West <elizabeth(a)eawestwriting.com>
Subj: A New Look at How We Write Content for the Desktop User Guide
Date: Fri Oct 3, 2008 10:18 am
Size: 9K
To: fedora-docs-list(a)redhat.com
Hello All,
I am a fairly new contributor to Fedora-Docs, and a <1 year Linux user.
My background is predominantly writing, so I approach the documentation
more from a literary stand point than a heavily entrenched computer
user. If anything, I'm a good example of the type of person you are
looking to convert from proprietary software to open source.
I took a hard look at the Desktop Users Guide F9, specifically the page
giving instructions to install financial software. First, there was a
large issue with the content-- the instructions simply would not work
for a new user with Fedora 9. Second, the instructions were not clear
for a brand new user to Linux.
After finishing the content change, and major style changes to the
Financial Software page, I deconstructed the changes and differences so
others may learn from them, and contribute their own ideas and
experiences. Yes, we are writing documentation for free, but we have an
opportunity here as open source enthusiasts to use our piece of the
project at large to further the cause and acceptance of Fedora as an
operating system. These suggestions below are only for the Desktop Users
Guide, the specialized guide for new users of Fedora, presumably coming
from Windows, without Linux experience.
For discussion purposes, this is the old page:
https://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Financial
This is the new and improved page:
https://fedoraproject.org/wiki/User_Guide-Financial_Software
Here are the major improvements I want to point out as potential "best
practices" for future work on the Desktop User Guide:
* The page stands completely alone for a new user.
Links and everything are great, but switching to a new operating system
is highly nerve-wracking. I have done this 3 times in the last 5 months,
including my first switch to Linux from Windows. Experienced Linux
users take so much for granted, when just something as simple as
installing software from a command line is foreign (a distant memory for
Windows users who remember DOS). Ease new users' frustrations by
providing all needed instructions in one document page or chapter that
apply to functionality, or getting something done. Certainly link to
topics that may be of interest to me for other actions, but don't leave
out information I need to accomplish what I want/need to do right now.
It's like giving landmarks when you give someone directions for the
first time, instead of letting them rely just on Mapquest, or sending
them an entire road map for the state.
* Stand alone chapters fit in more with how all users utilize help
manuals.
We're all guilty of this one. No one voluntarily reads a help manual
from cover to cover unless he or she absolutely must. New and old users
alike use an index for printed manuals to jump right to the information
needed, and electronically search is a godsend. Working to write and
offer stand alone chapters helps the users help themselves in the manner
they naturally will try first. The fewer places a user must go for
information, the more likely he or she can use the data effectively.
* White space is visually pleasing in print and electronically.
The old version crams together two sets of instructions to perform the
same task, without clearly delineating when the desired result is
accomplished in either situation. The new version sets off the simple
sentence "[Application] is now installed on your computer." with a
double line space on each side. This naturally draws the eye to the
completion of the first set of instructions, without a garish ALL CAPS
or other formatting scream. Breaking up complex instruction sets with
this practice re-focuses the reader's attention. This is vital, as it is
likely the user is hopping between windows, reading directions, and then
carrying them out. Under the old instruction set, a new user from
Windows very possibly could install with the command line, miss the
concept that terminal and Pirut are two different methods of the same
thing (after all both are new to the user), and keep following the
directions ticking that box to remove the application. Over and over
again until they decide it's just broken. The new page lets the reader
know in the introduction two installation methods are available, and
then uses white space to reinforce the distinction.
* Give Graphical User Interface(GUI) example before command line,
if possible.
The Desktop User Guide has an audience of someone with no previous Linux
experience. So, start with what is familiar, and move to the unfamiliar.
The prevalence of Windows has made mainstream computer users clickers,
clickers, clickers. Even shortcut commands are forsaken in the culture
of right-clicking. Windows has trained people to click 'Next', a
seemingly infinite numbers of times, and follow baby steps. It will
naturally occur to the new users how powerful and efficient the command
line is to Linux. Eventually, they will get to where they want to do
something beyond the scope of the Desktop User Guide and it will only
have instructions for the command line in a forum post or other
documentation. Starting out, it's enough for them to know it exists and
it will accomplish the same tasks as that clicking. Now, if the topic is
on the command line commands, there is little reason to start with GUI.
* Qualify the information the user is reading.
One of the largest differences between Windows and Linux a new user
immediately encounters is just the sheer increase in information his or
her computer is sharing. On top of the increase, the computer also
demands new decisions the user never had to make before. What do you
mean I have the option of NOT installing these other packages, the ones
you are telling me will make this package I do want work? People are
naturally intimidated by notations they do not understand, like the
numbers with decimal points under a package's name in Add/Remove
Software. With instructions, leaving out actions or messages the
computer will give confuses a new user. It starts questions that stop
the process of learning: Is this normal? Where is this in the
instructions? Why can't I find this step? Did I mess up? Going back to
the landmarks concept when you give someone road directions, I added the
messages Add/Remove Software gives while it is performing the user's
requests.
This is from my personal first experiences with Add/Remove Software, it
was s......l......o......w (I fixed it when I disabled the auto-updater,
not advice I want to share as a good habit to get into). Everything
else, Internet, chat, was moving very briskly. As soon as I quit
everything and just started Add/Remove Software it was still so
painfully slow even I gave up a few times trying to install GnuCash. If
I was reading instructions, the "Downloading repository information"
landmark would at least reassure me the application was still working,
not stuck or refreshing itself.
Some other quick notes:
* Changed icon info to "associated" as neither installation method
auto-creates desktop launcher. Didn't get into that because it
doesn't fit the "do I need it for this function" litmus test.
* Clarified confusion the first page had of Live-CD versus DVD to
plainly state DVD has both, does not install automagically, if
you do not have Internet access use the DVD, otherwise..... list
of instructions to install.
* Qualified the information that suddenly appears in the bottom
boxes when they tick the box as just extra information so they
don't think it affects the install.
* Included [y/N] step for command line so the new user isn't
hesitant about answering yes. Anytime a Windows user encounters
typing 'y' or 'n' it's not usually a good thing. Also, again
qualified all that test the Terminal spits out is just
information about the application so they don't try to keep up.
* Opted to teach Search box rather than clicking Office category
because Office category takes too long to populate, and new
users will be turned off trying to find the exact name of the
package to install from that long list when none of the icons
are different.
Limitations/Criticisms
* Have not placed in links to those "extra words and concepts"
like KDE Desktop Environment should link to the page about that.
I don't quite understand yet which are new versus old, versus
frozen in the document structure (many all look the same to me).
I need help to add that in.
* Have not taken my editor's scalpel to the wording. I know there
are a number of passive sentences, but I am too close to the
text right now to see the problems or areas for improvement. In
a few days, I can better judge nuances in wording.
* Other writers may not care for this style as it is more
involved, and fights against the elitist concept of self
discovery that is so common in the open source community.
* Other writers and Fedora doc leaders may not care for the
writing style because of the departure from the traditional, or
view it as repeating the same information over and over again.
* Many others I'm sure.....
I invite others to weigh in on this issue. I am very open to hear
criticism and realize critiquing my content is not the same as
critiquing me. :) I want to offer my strong English background to help
our group as a whole start to question when we work on documents: Who am
I writing this for? What knowledge will they already know?
Always Smiling,
Elizabeth Ann West
--
fedora-docs-list mailing list
fedora-docs-list(a)redhat.com
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
15 years, 7 months
Wiki-to-XML for F10
by Karsten Wade
As of last night's scheduling exercise, we have 09 October as the point
we need to make some kind of XML come out of the wiki.
Before we converted to MediaWiki, Mike McGrath had heavily customized a
script for Docs to use in converting, and the output was as good as we
had from Moin. That is our fallback position.
Can someone point me at the proper combinations of what to see if I can
use the python-wmlib and etc.? Between Paul, Ian, and Mike lie those
answers, I think.
cheers - Karsten, who wants something to schedule!
--
Karsten Wade, Community Gardener
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41
15 years, 7 months
Re: [Ambassadors] Special visitors at the upcoming NA Ambassadors meetings
by Clint Savage
On Fri, Oct 3, 2008 at 8:30 AM, Francesco Ugolini
<fugolini(a)fedoraproject.org> wrote:
> 2008/10/3 David Nalley <david(a)gnsa.us>:
>> The NA Ambassadors meetings will have visitors over the next few
>> weeks. These visitors will be representatives from other projects
>> within Fedora. The will attempt to educate us on the specific 'Join'
>> process for their project as well as tasks they have that are suited
>> for new users. Since one of the purposes of the Ambassador project is
>> to recruit and foster new contributors we figured that we at least
>> need to be familiar with the quirks for those projects.
>>
>> The first will be Máirín Duffy (mizmo) from the Art team at the
>> October 7 meeting at 2100 EDT (October 8, 0100 UTC) in #fedora-meeting
>>
>> We already have Docs and QA/Bug Triaging lined up as well, and we will
>> get others lined up in the coming weeks.
I'm confirming docs for October 21. Karsten Wade (and possibly
others) will be along to help us see the vision for the Docs project.
As far as urls go and our homework for Monday Oct 20:
Please Read
http://fedoraproject.org/wiki/DocsProject/Join
http://fedoraproject.org/wiki/DocsProject
To get more information for this group.
15 years, 7 months