what makes you write community documentation?

[Dan Smith]

On 8/15/07, Karsten Wade <kwade at redhat.com> 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. :)


LOL at least I'm not alone. Tab mix pro I consider essential :) The
session manager and what ones are compatable with which is a little
confusing. Lately I've been getting a number of corrupted sessions.  I
once added the tab counter extension just to see how many tabs I
literally do have open. I usually have 5-15 windows open with dozens
of tabs each. Got over 100 when I used the tab counter but figured it
was wasting ram and took it off.

> >
> >         [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 part of the admin skeleton approach I proposed people writing
smaller sections. The example I used was printing to PDFs. That topic
is about half a page to cover in detail and by breaking it into
smaller peices I think people can find more time to tackle such a task
than to try to do the whole printing topic.

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

Run the Xen and am curious about QUMU is it? Also use DOSbox to run
some treasured ancient DOS games :) What I haven't done was take the
time yet to figure out how to create a virtual image to use with Xen
and such. Used VMWare extensively back in the late 90s and early 00s.
Unfortunately too poor to afford VMWare and have been itching to use
Xen. Though I've found the Xen kernel to be very picky about hardware.
Can't use it on my AMD 64, at least out of the box. I'm sure there's a
way to get it too work. Just haven't had time to dink with it. I have
an ancient MIDI app that converts guitar notes as played to standard
notation from a special pickup that I've yet to get to work under a
virtual machine. Hoping it'll work under Xen, but I have to use Win95
as that is all the software understands. Wine didn't like it. App
loaded but wouldn't talk to the pickup :(  I also used the Crossover
plugin for a short time but found it was a waste of money. Better ways
to do everything than Crossover. So I have moderate experience in the
virtualization topic area.

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

I am surprised that Fedora is so adament about the current
partitioning scheme. I remember RH days it wanted to create a zillion
partitions by default LOL. I was doing the opposite back then and
condensing partitions. For servers though /var really should be a
separate partition. Can't count how many times I've been called in to
rescue a system only to find MySQL or Apache had filled up the root
partition with logs. Deleted the logs and all was well.
.xsessionerrors has a nasty habit of filling up /home and if /home
lives on / then the OS gets to complaining.  Those are all topics I've
covered on the partitioning guide I wrote for this group. I also
covered dual booting, use of a /data to separate configuration from
user data, creating partitions for document sharing, small drive
partitions, dedicated server partitioning.  All have their own
considerations.

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

I could expand the run level description. For the most part most
people today only use Run level 3 and 5.  There's a couple run levels
I'm pretty foggy about and most I haven't used in years if ever.
Though I once did an init 0 just to see what the run level was like
LOL  I found out pretty quickly :)

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

I'm not good with time. Ask any of my ex's, in fact my poor time
utilization skills (such as saying I'll be back from jamming at 10pm
and getting home at 1am) is one reason I have so many ex's. For some
reason the ladies take exception to fuzzy time estimates :)  So I'll
defer on the time per document estimate.

That does bring up the idea. How can we shorten the time it takes to
write a section without reducing the quality of the output?

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

Good point. I hadn't considered the translation issues. Makes sense
now when dealing with screenshots as it would be impossible to get
translated screen shots and keep them synched and up to date if there
were very many of them. Would be interesting to see if Babel fish
could speed up translations. People fluent in both languages would be
needed to create usable translations. If something like Babelfish
though could do the bulk work and translators were left with fixing
grammar, fixing translations errors and correcting minor things of
that sort it could greatly speed translations or it might take longer
as the translations are so badly mangled that they are worse than full
manual translation. Even in 4 word drive to beat a pun :)


> > Which brings up text editing.
>
> Each content type (writing, audio, video, etc.) could use its own
> stand-alone guide.  In the meantime ... :)

Ah. makes sense.

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


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

What were we talking about? :) J/K... On this I'll refer back to
micro-tasks to create workloads that are better suited for individual
expertise and time constraints.

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

Point taken.

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

True, sometimes CLI is quite resource intensive but also the only
practical way to go. FC3 for example so badly mangled my internal
network's settings that It wasn't until FC6 that I even thought about
using a GUI to configure networking again. Every time I even
accidentally hit the network tools it'd reset my netmasks and such.
Though I am curious why the MAC is included in ifcfg files for more
recent FC versions. It makes copying old versions a pain. Until
recently I'd just save off my ifcfg files and copy them strait in and
have fully functional networks in seconds. Now I have to do a GUI
config to detect the MAC, swipe that and merge it in. If I leave out
the MAC the nic card can sometimes get flaky on me. That's one thing
I'd LOVE to see documented by somebody. I'm sure there's an easier
way.

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

Which is?

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

Actually it begs the intended audience. The project is not likely to
be able to maintain extremely in depth documentation any time soon and
that does not seem to be the intent even if the resources existed. So
highly experienced users won't find many of our documentation efforts
useful. Only in areas they've never really done anything. Users with
medium experience levels will I suspect periodically visit the docs.
That leaves new users as the vast bulk of our audience. I suspect
%99.9 of these new users will be coming from a windoze background.
Fedora being the top distro out there it will be the one that windoze
users tend to gravitate toward and it also has the friendliest distro
for a recent windoze convert.

A second aspect is quite literally Linux is in a fight to the death
with M$. M$ has openly and less openly attacked Linux on multiple
fronts. The only thing M$ really has going for it is momentum. If
Linux gained a %30 desktop share the other %60 would convert rapidly
to Linux. If LInux cannot obtain at least a %20 market share in the
next decade it will not be supported in hardware advances and all the
gains we've made will evaporate as M$ will finally find a way to
exclude Linux users from essential abilities or even the ability to
run on new hardware which may be owned totally or partially  owned by
Microsoft. For example look at their tactics in the game market. Linux
support was starting to come out by many PC games makers but once M$
bought into most of the game makers and deliberatly put the others out
of biz few commercial games were distributed for Linux. If M$ were to
do the same thing with hardware manufacturers then the Linux community
could be SOL. A %20 market share of desktops would assure that there
would always be a profitable market for Linux compatable hardware. A
%30 market share would see the tide rapidly turning just as Firefox
has eclipsed IE in the browser wars and is gaining serious momentum
even still.

So Linux advocacy I feel is an essential aspect of any Linux
documentation project. New users come in scared. They are confused,
bewildered and chant the mantra of "I just want it to work" but in
reality they mean I want it to work in a way I am comfortable with.
Linux still carries with it some stigmas. Some are false such as
windoze being easir to install or run. Linux is by far easier to
maintain and install than windoze. Others are true. You can't go buy
bleeding edge hardware. There is almost certainly no Linux drivers out
yet for it. In the way of games Linux is finally making some inroads
but it's still miles behind. You call tech support I've found the
quickest way to either get hung up on or esculated is to tell them you
use Linux. You wait for that little gasp of fear as you've just
stepped miles past their comprehension and they then transfer you to
the 2nd level support who often know nothing about Linux but at least
are technically know something besides how to look up answers in a
knowledge base. To overcome this Linux needs to offer positives that
are obvious to a new user. To somebody who isn't going to yet be aware
of the durability or efficiency in which Linux leaves Windoze choking
in the dust.  The best way in my opinion is to turn them on to apps
they cannot live without. Addict them to Linux apps they cannot get in
windoze or that are not as cool in windoze as in Linux. Show them some
eye candy. Make them feel at least a little technically enabled. Give
them knowledge that helps them control their own computer but parcel
it out in digestible steps. All it takes is one important app that
annoys a user and they go back to the comforts of a known evil. When I
crutched into Linux back in the mid 90s I still did all my interenet
stuff on windoze.  It was just plain easier to my perception than
under Linux. The reality was Linux would have given me more control
but I didn't know that. The docs were either too sparse to be useful
or to cryptic to be useful. They assumed Nix expertise and were
written in the old school manner which will be very unappealing to
those crossing over from the windoze world.

So basically I see this not as a niche but a core part of what the
Fedora docs are about. The majority of our audience will be windoze
converts in the first year or two of the conversion process. While it
would be out of place to doc windoze/Linux equivs in the main topics,
a good list of such would be a good idea. More so when writing it
would be I feel very important to phrase things in ways windoze
converts will understand. To be Linux advocates and to addict new
users to the whiz band things Linux has to offer. When showing a new
user what Linux is about the place I start first is the wallpapers for
desktops. I know it sounds trivial but it's eye candy that windoze is
incapable of matching. Right there in the first seconds I've
established that Linux has things to offer that Windoze cannot hope to
match and I did it with a few quick clicks of the mouse. This helps
batter down resistance when I start explaining more technical
advantages and lends credibility to me when I start talking about how
Linux is a better multi-tasker how you don't reboot Linux and how much
control you really have over your own system. KDE has more eye candy
and the key bindings on KDE apps are more likely to be CDE which will
close match windoze apps in menu formats and in shortcut keys. This
means a smoother transition. Less of a learning curve. I point them
too apps like K3b, XMMS/Audacious because again they are very well
written apps that look nice, operate extremely ruggidly and will have
little or no learning curve for them to adapt too.

Think of every app they can use without having to read docs except to
find that app as them getting deeper and deeper into Linux. The more
apps they can master quickly the more likely they are to dive in and
become long time Linux users. The more comfortable they are with their
favorite apps the less they are likely to miss windoze and the more
tolerance they'll have to the stigmas that remain with Linux use.  The
more of them that switch the less stigma all of us Linux users face
when it comes to calling tech support, getting drivers for bleeding
edge software and being able to use a site like Rhapsody with full
support for everything. It also is an advancement for all FOSS
software. Firefox and MySQL have really opened peoples minds to FOSS
and usage of those apps has in turn put Linux in a kinder light. The
old can't get support misnomer is fading away and M$ has to come up
with a new lie to attack Linux with.

Anyway that's my $50 on the subject :)  No wonder I'm always broke :)

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

Done and posted to the list. I'm sure it will generate a flurry of
posts. The flurry of posts will likely generate greater interest which
will in turn hopefully generate more active writing. Perhaps even
people racing to pick the low hanging fruit. At least thats the idea.
Submited the admin guide today. Will submit the user guide same way
hopefully next week.

> Can you start this ...

Working on it.

> > 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?
>
Already did.

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

The translation issue to me is the best reason not to include lots of
screen shots. Makes sense for most topics as the attempt to recreate
those screenshots in other languages would be impossible to maintain.
Some topics language is not really an issue as they only want a
general idea of the interface and will seek out details.


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

 I think I'll let somebody else do that :)

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

It's cool. After reading your comments I'll edit to remove references,
though your attachment didn't come through. Only file attached to the
email was your sig.

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

Because it may or may not be installed and is quite time consuming
given the large number of potentials. A quick glance can narrow it
down to 2 or 3 for them and those they can load rather quickly and
easily try.

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

Cool, that's basically the idea.

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

In general Gnome key bindings are rather random and often frustrating.
One reason I don't use Gnome is that I've been using CDE since before
M$ adopted it. I like it, I know it and I face a learning curve to
relearn a bunch of keyboard shortcuts that are typically CDE in KDE
apps. So no learning curve there. Few KDE apps use other than CDE key
bindings and the user interface in KDE apps tends to be pretty
uniform. There are of course exceptions. Just going by the bulk of the
apps. Speed tends to be relative and often a non factor as
functionality and interface often override app execution speed. I will
gladly use an app with better UI that runs slower because it's a more
satisfying experience and because after you factor in UI contstraints
it takes me just as long. Since Linux is an excellent multi-tasker and
so little needs to be done that second among computer tasks if it
takes 30 seconds longer to do the same thing but is easier to use the
easier to use will win out every time. It is often 20 mins or more
before I look at it again anyway as I'm off hitting a web site,
writing an email, creating a doc after launching the app. It is not
like windoze where you have to sequentially complete program execution
to move on to the next task. I run multiple machines and may have
dozens of active tasks running on these multiple machines. So time to
run on most apps is really not a factor. Though I'm considering
removing Beagle from all my systems if I can't find an easy way to
background the thing. The indexing is gruesome on CPU time and refuses
to be nice.

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

I am not the right person for gathering the links as I've failed
miserably in account creation LOL. I remember now what the problem
was. When I first registered my GPG sig there was  a glitch and it
wasn't imediately availible. So I created a new one. That one was so I
signed my CLI with the new one. Then I applied for an account and had
3 GPG keys registered to me and it caused some sort of issue for the
account creation. Which got me bounced around to various people. So I
tried to start over creating yet another sig, then going through the
whole process again and that just added to the complications. So I
really have no idea which key is the right one to use. I'm also out of
email addies to create new ones and the delete function does not seem
to remove the email addy from the db only the key. It's at a point
I'll never remember my login info if I have to use a throw away addy
to generate the key and re-register yet again. Anyway I think that's
the limbo I'm stuck in. I'll give it another try again tonight.