On 8/15/07, Karsten Wade <kwade@redhat.com> wrote:
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.
Your welcome. I've always been rather outspoken :) So I'm good for something at least :)
Capability isn't the point, IMO. HTML is wasteful of bandwidth, forces
formatting choices and HTML requirements on MUAs, and isn't really
necessary.
Aye but Gmail and most web base email is HTML email period. With Gmail I can use pop3 but that means changing my password, actually it means unsubscribing since I use this email for important and work related tasks and pop3 sends the password in the clear. So I have to unsubscribe with this email addy, resubscribe with a new gmail since it's the only free email that I know of which has pop3 access. Then I can send in plain text. I can view in plain text all day long LOL. Just not send. My ISP is a cable modem and they may now support pop3. Don;t know. Was with Roadrunner so long and it was such a pain to get it run under Linux in the olden days that I quit using ISP based email long long ago. Technically I could point a domain at my machine, use one of the dynamic IP sites and host my own email on this machine. Just seems like a great deal of work to introduce a potential security vulnerability to my system with no gain in functionality.
I tend to agree with you about the waste of bandwidth. All those useless tags can triple or quadruple an email's size but if you do want to do some fancy formating it is better than the propriatory formats that existed before HTML became the standard and better than opening attachments. Though it does introduce potential java script vulnerabilities into the email.
I HATE flash period. Under Linux it is truly torture. There is a serious mem leak in the flash plugin for Firefox and once you visit a flash site Firefox is doomed. It will eventually consume all mem, usually in less than a week and then all those 50-100 of tabs I have open have to be reopened. I have to re-login into dozens of sites assuming that the session manager hasn't corrupted the session. Then I have to go into the history and get at those sites from there. So your preaching to the choir about flash.
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. :)
>
> This is in direct conflict with Paul's comments.
Paul basically said that only one way should be documented. He appears to be strongly opposed to the idea of documenting different ways of doing things.
[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. The partitioning scheme is for starters unworkable for me. I don't use the upgrade function. When I move from one Fedora version to the next I format the root partition. /home and /data contain all my user generated data and config files. Except for backing up a few things from /etc I can safely format / and lose nothing except having to install those thousands of packages I like to clutter up my hard drive with. I can't help it. I get into yum extender and see so many cool packages or figure I'll give this or that a try this time around LOL. The second aspect is many packages I consider essential for a bare functional machine such as K3b are not installed by default. So I add KDE, KDE admin tools and spend a good half hour removing and adding software on every install. I might be building a server which the default Fedora install is not well suited for, or a desktop again it's not well suited. So I have never once done a default install. Just not practical in my opinion. What I add or subtract depends on who and what I'm building the machine for. Much of it can be done post install but for many packages the installer saves a great deal of manual work opposed to configurations that need to be made if you install from yum, tarballs or rpms. So I prefer to get the core of the OS installed from the CDs right off the bat. Most of what I consider essential software lives on the CDs. It's just not installed by default. Many apps like Krusader are easily added afterwords and krusader is just nice to have not essential.
What I do not see is how for example when talking about file management how a discussion of file managers is either confusing or difficult. 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. Make that easier for them and you've improved their Linux experience by orders of magnitude. Nautilis and Konquerer to me are poor file managers. They imitate Microsoft's very poor file management user interface but many people love that style of interface. If I were to write a doc and only cover Krusader I'd be doing the topic a great disservice. A major reason why people would visit such a topic is not to know what a file manager is. They'd never found the doc if they didn't know what a file manager is LOL. It is to help the user. In the case of file managers it would be to present different types of file managers. Krusader and midnight commander represent the popular Norton Commander style interface while Konquerer and Nautilis are based more on the Microsoft file manager which is really a windows version of the PC Tools file utilities. Both have a great deal of configurability and it would be out of scope to spend a great deal of time on that. Placing a link to project/document sites about that software though would not be confusing or out of scope. It would be informative and after all isn't it our job to distribute information?
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.
I posted a quick example of documenting KDE, Gnome and command line in the same set of documentation. While I need to do a serious rewrite on it as for wording the concept shows that there can be clear documentation that shows multiple ways to do things under the same topic. If a user keeps seeing all these nifty tools that exist in another desktop then they might just get the urge to try that desktop. If they do they might like it better. If they like it better they will be happier as Linux users. If they are happier as Linux users and more productive then it is good for the Linux community. Doesn't matter what desktop makes their heart sing long as their heart sings. Am I wrong? The best way is to show some of these tools and give them places to branch off to explore such tools. Again one of the hardest jobs in retaining new Linux users is getting them too tools they like. The default apps for any Distro I've tried are not the apps I would normally set a new user up with and sometimes ones I would NEVER allow a new user to use if I wanted to see them stay with Linux. VI for example. You want to scare windoze users away show them VI, or worse make them use it :)
Which brings up text editing. You have Open Office, Abiword, Koffice, Kedit, Kate, Gedit, Scribe, Lnxer(sp) Emacs, Kwrite, Nedit and I'm sure I'm forgetting a couple commonly used packages. For most people Lnxer is not the way to go but for a few it will be heaven. I've found that kedit is like notepad on steroids and by far leaves windoze users the most comfortable when doing raw text editing. Most will prefer Open Office but Word Perfect fans will find Abiword a far better match. Abiword also has built in grammar checker, a thesarus package and is far easier on system resources. So a user who's running on a machine with minimal hardware may well need Abiword and be unable to really use Open Office. They flip open the Fedora docs and find that Abiword is lower on resources and suddenly they find that they don't have to buy new hardware. They can do word processing on that ancient machine. That to me is the purpose of such documentation. I haven't run Koffice for a bit but if I were to tackle the subject I would and would give as objective a description of the pros and cons of the Koffice suite. The idea is to promote Linux by delivering the best fit within reason for what people do. At the very least give them a choice. Fedora does so with it's install packages and repositories. Why should we documenting it ignore those same packages?
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.
The way I see it is that if we get to the doing part we will see more help in the co-maintaining problem. In some areas there will only be one person and even nobody with the required level of expertise and interest to do a respectable job. Still some docs is better than no docs wouldn't you say?
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.
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?
So, we repeatedly ask for help in documenting KDE defaults.
I'm more than happy to do so. Though I do see a problem with KFedora vrs Fedora. It tends to make KDE users feel like 2nd class citizens. I posted a nice rant on the topic of kbuntu vrs Ubunto on the Ubunto forums for this same reason. Fedrora is not Gnome, it just defaults to a Gnome desktop. Probably most people run other desktops. Fedora is independent of the desktop manager and many machines running Fedora do not even have X installed at all. In my opinion the Admin guide and basic user guide are desktop independent. Then have a KDE, Gnome section each for specifics to those desktops such as how to add to menus, change screensavers and so on.
Speaking of machines not using X. Many of the documentation guides make no provision for command line equivs. This is an issue for those who are not running a desktop manager or those running a minimal desktop manager. Other people will turn to the guide to help configure one of the many dedicated hosting servers out there running Fedora. They will do most or all of their configurations through SSH tunnels or usually rather clunky web based GUIs. So for things like file management, permissions and many other tasks it is very important to cover the command line as well as the GUI methods of doing things.
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.
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. So for me Gambas is part of the default since it's part of the extras repository and a stunningly good replacement for VB. Any talk about programming IDEs that neglected Gambas would be doing the topic a disservice. Kdevelop, Ajunta, Glade, and so on are all must covers I feel when it comes to programming IDEs. All in official Fedora repsositories. Maybe there's a difference of opinion there since I find the default Fedora workstation install as defined by you click on default install so limiting that it's not a usable work station. It does nothing for Linux advocacy which I see as a big part of our unwritten duty and it does not help many people since in the real world few use that install. The real world is my focus. Most Fedora users I know do not install many apps not found in my deffinition of default. There will be an occasional tarball or driver and there is support needed for media formats and such. But the bulk of their software can be found on the CDs/official Fedora repositories. So to me while it's a much broader class of software it is also more in line with real life usage. I'll admit I've only helped about 40 or 50 people transition to Linux specifically using Fedora. I recommend Fedora as a distro anytime I have influence in the decision. One of the reasons is that Fedora has such good support for so many good packages. Far fewer things you have to hand install. I also maintained some large networks with Fedora being the default distro as well as participated in various Fedora lists and forums and general Linux forums and lists. So my sampling of Fedora users is only hundreds of users. In all that time the only users I ever lost back to windoze were ones using default Fedora installs.
That is my personal experience. To me it says if we want to keep users we show them more than one way to do things. As for resources. I need to spend probably 2 hours editing the services doc I wrote.The wording and grammar are very poor. I added about 2 minutes to the writing time to support both KDE and Gnome. Turns out there was only one difference between them. That is the first place you click. Still I used switchdesk to start a Gnome session to double check. I spend more time on the command line section than the GUI but feel it was quite essential to the topic. So supporting both took a very minimal time. I need to install XFCE so that I can document using that as well. As a writer I feel it's my job when covering a topic to be up on all 3 since all 3 are used frequently. My personal preferences may be with one or another but that doesn't help the end user who may be using something different. So I waste a bit of drive space with a window manager I don't actually use. Given todays drive sizes few if any on this list will notice the extra half gig to add all 3 window managers. Nor is it a great time expenditure to spend some time doing research on a topic. After all isn't research a crucial element in any type of writing?
Most of us have technical backgrounds. So the research element will be mostly trivial if they are not accustomed or easy enough to get a co-writer to fill in the equiv in another desktop. For example somebody wanted to know what the KDE counterpart of say GRIP is I'd be happy to write up a quick doc for them or point them at that app. 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.
>
> 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.
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.
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
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.
> We have made a conscious decision to provide information to
> users who
> may not be familiar with what is obvious to you and I.
[...]
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.
Ok, I was following convention by providing lots of screen shots. 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?
In the case of file managers a screen shot can say what would take pages to say. 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.
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.
That sounds fair to me.
>
> 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.
In many cases though there are only trivial differences in usage but big differences in looks, speed, key bindings and such.
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.
That is actually the case for most. For services, network configuration, Samba configuration, NFS and really most topics there are only minor if any differences. Usually it's because the default Gnome menu now sits on top and has the System seperated from the start button. So there's a different starting place but the rest of the steps are exactly the same. When it comes to burning from Nautilis and Konquerer it's pretty much the same. K3b, Gnomebake, XCDroast are the more traditional style of burners. Covering K3b would cover the basics for these and a quick link and screen shot would be sufficient to make users aware of alternates. When it comes to partitioning KDE defaults to QTparted and Gnome to Gparted. Essentially the same software. Diskdruid is what both see when doing the install. Parted and Fdisk are desktop independent and not even X apps. So especially with the admin guide there are few major differences.
When it comes to look and feel that's where the split is prounounced. So for the KDE guide to me it'd make more sense to go after KDE configuration rather than how to burn a CD or rip audio files as those tasks are more or less desktop independent and each desktop offers multiple ways to do the same thing. Covering every possibility is of course too much but a happy middle ground I feel would best serve the community while being both practical and useful.
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? :)
There is no shortage of good will on the list. We are of a common purpose and I've seen no hostility or malice from anybody on the list. I don't think anybody feels that anyone on this list is intentionally obstructing or playing personal fiefdoms or anything of that nature.
> 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.
Yup it is. 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. Any kind of documentation can be hard to do because for most people writing it what you are writing about is second nature. You've done it so often that you often forget the middle steps or reasoning or other essentials that a new person won't have. It make sense to you because you've done it a thousand times and know where it all is already or got that painful step out of the way so long ago that you've forgotten it exists. When I was a coder I often was surprised at how much I left out of program docs I read when those docs met a real live user in my presence. Things I took for granted were not common knowledge to the end user. So I always tested my docs out on as green a user as I could get my hands on and took volumes of notes on questions they had, mistakes they made and mistakes I made.
- 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@redhat.com
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list