what makes you write community documentation?

[Karsten Wade]

On Wed, 2007-08-15 at 14:14 -0500, Dan Smith wrote:
> Sorry about the delay in replying.  Got buried in email after some
> hardware issues. 

Thanks for keeping the discussion going.  I know we may appear
adversarial at times, but I think it is constructive.  From my POV, I've
seen you raise arguments that I think are no longer relevant or are
based on misunderstandings.  It is helpful to ferret those out, and
maybe find a way to a common understanding.  Where there is validity in
the arguments, we need to be sure we are fixing stuff or know why it
isn't going to be fixed.

> 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?

Capability isn't the point, IMO.  HTML is wasteful of bandwidth, forces
formatting choices and HTML requirements on MUAs, and isn't really
necessary.  

Regardless, where the desire is to communicate, the most common method
is preferable.  This is why good Websites have ALT tags for images, are
usable without their CSS, and don't use images or Flash for needed page
elements.  I lump HTML email in with all of that. :)

> 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. 

[snip content about best of breed]

Sorry, without Paul's comment to compare it to, I'm guessing.  I presume
you mean his comments that we want to document the default installed
applications before we branch into non-defaults also available for
Fedora.  My comment above is that the reason we don't have the default
camera stuff well covered is a lack of resources.  Whoever is working on
the User Guide decides what are the priorities for coverage.  If there
isn't a person or time to get to cameras, it is not in that guide.

An important point to note is that no one is forcing you or anyone to
choose what to document.  If you want it part of Fedora documentation,
it has to be about software that is in the galaxy of packages, that is
all.

Our focus on the project has to be first on the default install.  It
doesn't make sense to focus outside of this until those bases are
covered.

Again, this is project focus, not personal focus.  You will be steered
to document e.g. gthumb because it is default, not because we feel it is
the best of breed.  That decision comes from the people doing the
development, packaging, and spinning.  

No one is going to turn down documentation about non-default
applications.  It still has to meet the same requirements of other
content, that is, it has to be well written, use clear and translatable
language, be maintained/maintainable, and other general guidelines.  If
it is about non-default applications, it may be harder to find
co-maintainers.  That is the challenge you accept when you focus on the
non-default applications.

However, in this new Fedora world, it is hard to know what is going to
be on a default spin.  It could very well be Kid3 etc., especially where
it is a KDE spin.

So, we repeatedly ask for help in documenting KDE defaults.

I don't think there is a contradiction.  We have a generic policy to
document the defaults of the various spins Fedora itself produces.  As
those spins cover more software as "default", our content has to expand.
What actually gets work effort is then dependent on resources and
timing.

If you want to see an application be documented as default, then you
need to do the work to get it recognized as the default for a formal
spin.  You can spin it yourself as the default, but then you are in the
same boat as above -- as a side-effort that has to be self-maintained,
even from within the Docs Project.

> 
>         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/WikiEditing#Getting_Edit_Access

I've been working for a long time at making it easier to get a Wiki
account.  There were technical and legal barriers.  We have overcome all
of them, and are just waiting for Moin 1.6 to be released for us to
migrate to it and have a click-through CLA.  Then you can get Wiki
access just by creating an account.  So, I'm very sorry for the
difficulties of the past, it was necessary to be that way, and now we
are fixing it.

> 
>         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. 

Part of the problem with not having enough writers on the project is the
task list is incomplete.

The folks doing the work around here are trying to make it easier to
find something to do, but we cannot take the time to enumerate every
single task in detail.  Aside from the time effort involved, it's also
not really the way a self-directed FLOSS community works.  We need to
grow contributors who are self-starters and don't require a detailed
task list forever.  In other words, those tasks are to get you started,
not keep you working for months on end.

FWIW, I think these are good tasks to get anyone started:

http://fedoraproject.org/wiki/DocsProject/Tasks/UserGuide

The reason the Admin Guide is only a template to be filled is because no
one is leading the effort on that guide.

>         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 



>         We have made a conscious decision to provide information to
>         users who
>         may not be familiar with what is obvious to you and I.
[...]

> 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. 

OK, I won't forestall with many suggestions. :)  Just remember that
content for the User Guide isn't the same as for the Admin Guide, and
the UG can always hand-off more details to the AG to cover.

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

They are.  However, if this is for GUI screenshots, note that we avoid
screenshots unless they provide something you can't get in plain text.
In such a case, they are typically diagrams rather than a shot of what
is most likely already on the user's screen.

I can't find the reference to this guideline; I thought I put it into
the StyleGuide:

http://fedoraproject.org/wiki/DocsProject/StyleGuide/

... but I can't find it.  I'll have to dig up the last post on this
subject, rework it a bit, and put it in the StyleGuide.


>         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.  

Note that again, the "Users new to the Fedora desktop working
environment" doesn't mean you can't write for a different audience from
within Fedora Docs.  It is just that our focus and resource directives
are around that.  So, for example, if you submit content for review and
it is clearly for application developers using LAMP on Fedora, it won't
get the same speedy response as content bound for the User Guide.
 
> 
>         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?  [...]

Mainly resources.  It really does take more time and effort to explain
usage of three applications instead of just one.  An iterative approach
goes roughly like this:

1. Document one application of every type that can appear in a default
GNOME install.
2. Document one application of every type that can appear in a default
KDE install.
3. Document additional applications that are popular/best-of-breed but
aren't necessarily the default in one of the upstream desktop
environments.

Note that we absorb many standards from the upstream.  KDE and GNOME
decide already what is are default MIME type handlers in their install.
Fedora doesn't tweak with that every much, aiui.

> 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. 

This is more a discussion of _how_ to format the documents.  This has
been discussed on list, and IIRC the decision was to have a GNOME app
and a KDE app under every section, by task.  CD burning, camera
transfer, etc.  Reasons:

* Some writers only know one or the other set of defaults well enough to
write about them; this lets them get involved without forcing them to
learn other applications.

* It is easy enough to explain that GNOME apps come from installing the
GNOME Desktop group, and KDE from installing the KDE Desktop group, and
it is possible to have both installed.  But just in case someone has
only one installed, here is an option from each grouping to cover the
task.

Still, we could just have e.g. "CD burning" and cover "a few common
applciations", making sure that one from KDE group and one from GNOME
group are included.  IIRC, the reason we did not do that was because
people are still being taught to know about the two desktop
environments, and we didn't want to be drastically different and thereby
confusing.

As the rest of Fedora erases the differences between KDE and GNOME for a
standard install, so can we erase the difference in our content.

[snip about red tape]

> My suggestion is just my impression as a new user and what I'm hearing
> in other new user posts. 

Agreed that this is an impression that I hear.  Glad it is obvious that
we are trying to make it better, eh? :)


>         The CLA looks like a hassle, until you need it.
> 
> Those complexities are ones I'm happy to leave to others :) 

Right, well, until it is perceived as unneeded red tape. :)
 


> 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. 

Right, definitely sounds like (ironically) an FAQ is called for.  I'll
start a separate thread so we can gather what in fact are the FAQs.

- Karsten
-- 
        Karsten Wade              ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
    quaid.fedorapeople.org        |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070815/10e42055/attachment.sig>