what makes you write community documentation?

[Dan Smith]

Sorry about the delay in replying.  Got buried in email after some hardware
issues.

Paul I use Gmail. I'll configure Kmail to send to Gmail to reply to this
list, but is anybody really still using an email system not HTML capable?

On 8/7/07, Karsten Wade <kwade at redhat.com> wrote:

I wanted to highlight this observation.  It is true, and as you
> surmised, the reason (for example) camera usage isn't covered in more
> detail is simply a shortage of writers.



This is in direct conflict with Paul's comments. Rather confusing to be
honest. I would be happy to go into more detail on camera usage.  To combine
a later comment. The default Fedora install is a base and nothing more. It's
not a usable system. It will never go over as a legit desktop replacement.
There is a great deal of software out there which is far better than
anything on windoze. However what is the right program depends on what you
are doing and who you are.  What is the right app for me to tag files is
Kid3. For somebody else it might be something different. For me the right
app to import photos is gthumb. I don't want albums, especially not until
the tag database is standardized between album software. Another use may
well want albums and that's it.  Not difficult or confusing to present best
of breed software for various tasks and links to their sites for details.


Anyone can get an account and edit this page:


I created several Fedora accounts but never had access. I got on the IRC
channels and asked and was directed to several different people but in the
end still had no working account. Where should I start?  Recreating a gpg
sig?  I should still have a wiki account, but it had no write access last
time I tried to edit anything.

http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Photos
>
> Account creation really isn't that hard, and helpful people are
> everywhere.
>
> > The problems I see with the project start with the complexity to
> > actually write something. First nobody knows what needs written.
>
> http://fedoraproject.org/wiki/DocsProject/Tasks


Ah but what needs to be written? When you click on a link it takes you to a
list of templates. The admin guide shows a list of topics but if you drill
down far enough it always takes you to a list of templates.


> I suggest a greeter committee spend some time in IM and or email
> > exchanges and get to know new volenteers. Walk them through the
> > process of account creation. How things work. Get a feel for their
> > skills and connect them with areas that need work.
>
> Extensive examples of this exist in the email archives and IRC logs.
> Project members have always made themselves accessible to contributors,
> new and old. Personally, I can't do much more.
>
> We need concrete suggestions that we haven't already tried.  We'll
> continue to beat that old drum as you suggest, but we either need a new
> rhythm, a new drum, or a new drummer.



A suggestion is a quick FAQ. The how to create an account was pretty good in
detail for example. Then when somebody joins up email it to them as well as
periodically posting it to the list as a whole so that changes can be seen
and people reminded of things they forgot. I never got an email telling me
where to start. I asked a question and was pointed to the account creation
link. I followed the steps more or less successfully though there was some
sort of hang up with my PGP sig which caused me to redo it.


> Second I suggest more flexibility in the docs. Lets show people the
> > strength of Linux, not restate the obvious. I gave some examples and I
> > hope I didn't offend anybody. I suspect that they may have had more
> > detailed documents but that decisions were made to make it ultra
> > simple. The problem is ultra simple got to be so simple it's useless
> > in my opinion. Lets take playing music for example.
>
> We have made a conscious decision to provide information to users who
> may not be familiar with what is obvious to you and I.  Content always
> needs improvement.  Just remember that most of the content out there is
> exactly like you describe -- it figures a relative familiarity with the
> technology, focuses on various ways to solve problems, and covers a
> diverse set of tools.  Why should we do it just like that?  This isn't
> the "Linux Docs Project", it's the "Fedora Docs Project".



Stating the obvious is fine if you don't stop there. I'll do up the camera
and changing services guides as real quick examples. In the services I'll
cover KDE and Gnome GUI tools for that as well as chkconfig.  I'll also give
a brief explanation of run time levels.

Which brings up a question. Png graphics the acceptable default?

In a default working environment install of Fedora, there are a series
> of menus.  It is those applications that are good examples of what to
> cover.  Beyond that is less useful, because it includes applications new
> users are not likely to see.
>
> > Topics I personally think should be covered are.
> [snip good topics]
>
> Anyone is welcome to cover those topics, within legal-in-the-US
> guidelines.  But as the Docs Project, we have to focus on one or a few
> things to be successful at it, and why not "Users new to the Fedora
> desktop working environment"?


I understand legal issues and will stay away from MP3s.


For example, there have been numerous requests for KDE content, but no
> one has stepped up to write it.  When someone does, we'll have it.  But
> it isn't reasonable to ask for a change in the commitment of resources
> for what you think is a good idea.



I'd be happy to write KDE specific stuff but why not cover both at the same
time?  My advice to all new users is to install both KDE and Gnome. Try them
both but at worst your going to use apps from both systems. I encourage them
to also try other window managers. I personally prefer KDE but know Gnome
well enough to document both. If a user has both systems installs it doubles
the possible apps for a given task and quite a few are not desktop
specific.  What I don't see is breaking everything up into if you use KDE
and you want to burn a CD do this, if you use Gnome do this. CD burning is
CD burning. Far as I can tell K3b is almost universal for that purpose among
Linux users. Even Gnome fanatics tend to use it. More so K3b is far closer
than any other reliable Linux package out there for what windoze users are
used too.  Still it makes sense to cover command line, Gnome specific
options in case they don't have or want KDE installed.  The time invested to
write such is minimal. Users will skip to what they have and want to do.
Details can be maintained on the project site so no need to go into details
or try to update them. Software covered exists in the Fedora install for the
most part. So it is part of the supported Fedora desktop or can be found in
Fedora Extras.


> In my opinion the red tape surrounding docs
>
> I'm sorry you had a bad experience.  It happens.  We all try to help
> each person with whatever they need.  There are many success stories,
> and an unknown number of failures.  People fall through the cracks, no
> matter how hard we try.  There is a reason that any barriers are in
> place, and we're always working on making them easier to hurdle.  But
> persistence always works out in the end.


Aye, didn't accuse anybody of trying to make things difficult. We are all
volenteers far as I know donating out time and energy to a common purpose.
We love Fedora or we would be using another distro or ack windoze.  None of
us are likely to make a dime off these efforts or get famous.  We are
argueing over the fine details not the big picture. My suggestion is just my
impression as a new user and what I'm hearing in other new user posts.


> Second do we really want people editing content directly?  Shouldn't
> > that go through a review before being placed out there?
> [snip]
>
> Few thoughts here:
>
> * You are suggesting adding a lot of work for a small group of current
> contributor volunteers.
>
> * Your model is a little out-of-line of the open source/open
> collaborative model
>
> * Does it really lower the barriers or just put all the barrier work on
> people instead of tools and processes?
>
> Wherever possible we need to make people able to control their own
> destiny in Fedora.  We need to hold their hand as much as they need, but
> not forever.



Makes sense. Just suggesting one way to increase the volume of content by
reducing the amount of work it takes to do work. Also as a means of quality
control.


> So it's more a matter of organization really. There are lots of people
> > who want to help. They don't know where to help, how to help. They
> > come in and feel like outsiders. The red tape is confusing. There is
> > no process to make sure they know what is expected of them. The work
> > to do work can be exasperating and confusing. Create a sig, create
> > accounts here, there and hope that all the various people in each step
> > get it right and that the new members do it correctly.
>
> Fedora has a responsibility to the longevity of the project.  Since all
> of this used to be a closed loop inside of Red Hat, opening up those
> resources requires care.  There has been a reasonable position between
> "no barriers" and "too many barriers".  For example, if we ever have to
> change our content licensing again, as we had to from GFDL to OPL a few
> years ago, we are *all* going to be happy that contributors and content
> are covered under the individual contributor license agreement (CLA).
> The CLA looks like a hassle, until you need it.


Those complexities are ones I'm happy to leave to others :)

> What I suggest is that this process is streamlined. The welcoming

> > committee can filter out the passing ships and filter based on
> > ability. They can walk folks through the initial process of getting
> > all those accounts created. They will actually know who to buzz if the
> > rights are set wrong. They can also help get people to areas where
> > they will do the most good. There are two types of people needed in
> > projects like this. The organizers who unfortunately will probably
> > spend more time working with people than on actual docs and the
> > writers. The fewer organizers the more get's written. The more the
> > ogranizers do the more time writers have to write.
>
> That sounds like what happens on this list.  Isn't that the case?
> People are welcomed, directed or led or left alone, as per their
> preference.  I understand that may not have been your experience, I'm
> sorry, but you use the third-person (they, them) as if you've done a
> wide ranging poll of people frustrated with Fedora Docs.


Generally people say hi, welcome to the list. Point them at a link that
generally leads to a template or other dead end. People then go away. Look
at how many new people have joined in the last six months and how few
contributions have come from them.  True a certain percentage would never
contribute a word no matter how easy you make it. Still statistically
something is wrong in the process with that high a rate of non-contribution.


Also there is no central FAQ or repository for information related to this
project. For example to get on IRC I'd have to search through my emails to
find the server or a link to the page that has the server listed on it.
There's no room listing at all. So if your not directed or don't do a little
exploring you don't even know what rooms actually exist. The GPG page is in
one place but other account creation info in other places.

That's my 2 cents.


- Karsten
> --
>         Karsten Wade              ^     Fedora Documentation Project
> Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
>     quaid.fedorapeople.org        |          gpg key: AD0E0C41
> ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
>
> --
> fedora-docs-list mailing list
> fedora-docs-list at redhat.com
> To unsubscribe:
> https://www.redhat.com/mailman/listinfo/fedora-docs-list
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.fedoraproject.org/pipermail/docs/attachments/20070815/c44183ca/attachment.html