what makes you write community documentation?

[Karsten Wade]

On Wed, 2007-08-15 at 18:10 -0500, Dan Smith wrote:
> 
> 
> On 8/15/07, Karsten Wade <kwade at redhat.com> wrote:

> ... all those 50-100 of tabs I have open have to be reopened.

You're like me in that regard (last session was 8 windows, 87 tabs.)  Do
you use Session Manager?  It is a real hero:

https://addons.mozilla.org/en-US/firefox/addon/2324

Tab Mix Plus is great in combination with Session Manager:

https://addons.mozilla.org/en-US/firefox/addon/1122

I didn't switch from Galeon until Firefox extensions had all these
features. :)


> 
>         [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.
> 
> 
> As for default install that I'm not as sure of.  I have never used the
> default install. 

Probably a good candidate for virtualizing and trying it out.  We have
to assume that the average user who installs from one of the live spin
media is going to not ask for more than is installed automatically.
That automatic set of packages on the GNOME and KDE live spins are the
"default".

> The partitioning scheme is for starters unworkable for me. 

There is a long-standing request to get /home as a default partition.
Meanwhile, we document around it.

> ... Why not cover file managers since it is a crucial part of how any
> OS works? Since they are the part of the user interface many people
> see the most of. ... It would be informative and after all isn't it
> our job to distribute information? 

I chose this snippage because I think it is a good representative
question.

Way back when people asked "Why is Fedora Docs focused only on short
tutorials and how-tos?"  The answer is that it is a full-time PITA to
maintain a real guide, like one of the ones you find here:

http://www.redhat.com/docs/manuals/enterprise/

It *is* possible for a community to do that level of work, but it needs
to build up to that.  In the intervening years, we have built/are
building infrastructure that supports that level of writing.  We can
really take on work from anyone, any group size, any amount of content.
"Bring it on," someone once said in another context.

What I get from your thoughts on this topic is that you think it is easy
to do the depth and breadth of coverage that you suggest.  I think you
underestimate the challenges of making Fedora quality documentation out
of these ideas.

> I posted a quick example of documenting KDE, Gnome and command line in
> the same set of documentation. 

That was a good example of how to interweave.  It was good depth, with
it getting richer the farther down you go.  I think it was good for the
Admin Guide, appropriate to reference from the User Guide.

For the docs you see on redhat.com/docs, figure that it is eight hours
of work to produce every page of the content.  There are industry
standards we could reference, and they are fairly accurate.  About four
hours to update a page, and two hours to maintain a page (check that it
doesn't need further updates.)  This time includes everything from
research, testing, QA, editing, and re-writing.

My point is that when we focus on one technology choice (the default)
over others, we cut the time for those pages.  Maybe not exactly in half
or quarter.  Perhaps third.

Oh, and there is a metric to apply to the translation side.  Where you
add in additional applications, you increase the difficulty of
translating and resulting QA, etc.

> Which brings up text editing.  

Each content type (writing, audio, video, etc.) could use its own
stand-alone guide.  In the meantime ... :)

> Still some docs is better than no docs wouldn't you say? 

To get "some docs" we need to either have a broad coverage that is not
very deep (just defaults, by spin type), or have deep coverage of fewer
areas.


> Agreed so why not cover the commonly used stuff at least at a high
> level and provide a link for users to do their own footwork to do
> detailed comparisons? 

I don't think we're in disagreement here.  The only difference of
opinion may be on how much work this requires of *other* contributors.
Each person is not of the same skill, experience, time, or attention
level as each other.


> 
> Speaking of machines not using X. Many of the documentation guides
> make no provision for command line equivs. 

Not documents I write!  In fact, skipping all the screenshot junk allows
you spend more time on quality CLI content.

I think, across Fedora, we have been mixed, but certainly tried to be
CLI aware.  Red Hat docs afaik always cover both methods, which is why
they are so resource intensive (see above rough formulas.)

> The default is a pretty varied animal even if you use only the
> server/desktop/whatever else default installs. I view default as what
> is normally contained on the Fedora install CDs or in the Fedora
> official repositories. 

OK, but we as a project need to have a proper definition of default.
The one we use in Fedora Docs happens to match what e.g. Release
Engineering means when they say "default".  At least, afaik.

> In all that time the only users I ever lost back to windoze were ones
> using default Fedora installs. 

You have identified a niche/audience we need to address.  We can do
that.  Maybe there is a sane way to do that.

* docs.fedoraproject.org/doc-name/ => focus on defaults per spin, broad
and not too deep, or deep and not too broad; proper workflow to get
content published, good publishing tools for self-service

* fedoraproject.org/wiki => all the content that is not in the above
docs, maintained at a quicker pace (fewer style or editing requirements,
more wiki/community style), more "rawhide" than "released"; pull content
from here for every release to bundle into docs.fp.o

> Most of us have technical backgrounds. 

Not really the experience here; it is quite mixed in terms of the folks
who have self-intro'd.  But anyway, we do expect people to do basic
research, even if they are just learning how; after all, we all have to
get started somehow.

> I'm just not seeing a large time investment in supporting KDE and
> Gnome and potentially XFCE. Second some docs are better than none and
> if nobody is around or willing to contribute the other desktop's
> section then so be it. 

Maybe we're just not vocal enough.  We have a serious active-contributor
shortage in this project.  Refer to the meeting summary from yesterday:

http://www.redhat.com/archives/fedora-docs-list/2007-August/msg00048.html

I'm personally beating my head against the wall trying to figure out how
to do it better.  I don't have much time, either.  I need folks like
_you_ to get on the Wiki and start writing stuff like the FAQ, etc.

> This sounds like a good place to review the task list. I've noticed
> quite a few missing areas such as text processing.  I'd suggest taking
> one section a week and building a task list from a concencious on the
> list. 

Can you start this ... 

> The same approach. If you'd like I can start with the admin list and
> build a topic list using this group to start discussions on what
> topics and where to put what sub topics. 

:) ... and this?
 

> Ok, I was following convention by providing lots of screen shots.

It is not really Fedora convention.  Just like we inherit RPM from Red
Hat-based distros, so do we have a love for DocBook XML and a dislike of
too many screenshots.

Diagrams are cool.  Especially SVG ones, doubly-especially when someone
hacks PO (i18n) support into SVG files.

> They can be a bit bulky and unfortunately change as the interface 
> changes, but can also say quite a bit. In the screen shots in the
> sample services doc I sent. Would any be useful in the final doc? 

I honestly never looked at them.  I looked to see if the content needed
any images, and it didn't.  It is also visually shorter without images
inline.  Much snappier read.  I just recreated the commands to get
content to paste into the {{{code}}} blocks.

> In the case of file managers a screen shot can say what would take
> pages to say. 

Why not just ask the user to load the application and look at it?

> In fact a screen shot, a line or two and a link to the project would
> probably be the best way to handle the file managers section. Users
> could in minutes narrow down their favorites, install them and be up
> and going. 

This is a different use case.  These sound like canonical pages for each
application, a sort of product page.  Like Freshmeat, or Amazon pages.
That is a good idea, I'd expect that is being worked on as part of the
Online Desktop, and so we can probably inherit those/use the upstream
URLs.



> 
>         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.
> 
> In many cases though there are only trivial differences in usage but
> big differences in looks, speed, key bindings and such. 

This is an interesting POV.  Teach the concept and then give a quick
overview of the ways to accomplish it.  Like fishing and handling rod
and tackle.  It can work, I just think it takes more rigor (time,
resources) than we can expect of most unpaid contributors.  YMMV.

>  

> 
> ... Reread the welcome letter to the latest guy to join the list. He
> was pointed at the translation section but the Wiki Account creation
> you put into this post for example was missing. So were quite a few
> things he'll need to get started.

Truth, and to be honest, I did that on purpose.  He came to translate,
and I had to presume he had found L10N/Join or he wouldn't know to
self-intro using the provided template.  He also mentioned an interest
in doing more technical/content contributing; my reply was intended to
elicit a reply from him.  Maybe I should have piled on URLs in addition?

Regardless, a single FAQ with a million such links would be a great
place to start and a nice single URL to hand over for all cases.

- 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/d404893b/attachment.sig>