Here is my take if your interested. To answer your first question I want to write so that I can contribute back. I am a one time coder but got paid too write in non-C based languages long enough I forgot all my C coding skills. Never really liked that style of syntax anyway. Linux is very heavily C/C++ oriented. So contributing code is not practical. Documentation is often skimpy, not especially informative and often obsolete to the point of being counter productive. So one reason I want to write is simply to do something useful for a community that has given so much too me. A second reason is I strongly believe in Linux. I believe in what it can do. While I hate and despise M$, that only got me interested in Linux. I love working in Linux and with Linux. It allows me to do what I want to do. I spend my time working on stuff not fixing my OS. Not dinking with settings or reinstalling things. No virus scans to run. No defragging or rebooting to fix a misbehaving app. No more saving every 2 mins because the app I'm working in might crash any second. No more watching my whole system go under because I installed too many apps or one app that did not work and play well with the rest. I can go on and on about the things I love about Linux and how it is superior to windoze. Most of them are positive reasons. For me KDE is an awesome window manager. The key bindings are natural and intuitive. I don't fumble in many KDE apps trying to figure out keyboard shortcuts. They are almost always CDE which is what I've used going back to many DOS apps. Even before M$ standardized on CDE I was using CDE shortcuts. I get feature rich apps that work and don't crash on me. The management of my window manager and system in general is well laid out, non-intrusive, easy to use and pretty much everything is 2 clicks or less away. Windoze, Gnome and other systems often hide/bury stuff several clicks down. Which leads to short cutitus. I really like the power of Linux. It is truly cutting edge in many areas. I love the stability. The security. Not relitive stability or security, it's rock solid. It's not comparitively stable it's really stable. Sometimes going six months to a year without any real problems that require user intervention. It's customizable. It doesn't hurt that it's free but I used to buy distros just to support Linux development. I've owned several RH versions and sub versions. Mandrake, SUSE, even bought a Corel distro once and remember eagerly buying Caldera 2.0 the first distro that I'm aware of sold at CompUSA. (Spits on Caldera name now). So for a reasonable price I'd bought Linux distros. I really like the OS that much. Even though I could get it for free I figured buying those distros, some of which I never really used like the Corel, man did that distro suck LOL, at least I felt I was helping Linux develop. So as a Linux advocate I want to do things to help Linux. In my opinion one of the biggest challenges is old guard vrs the new wave of windoze refugees. Man pages make sense to the old guard. They look like gibberish to noobs to Linux. Many times they tell you what you already knew but are useless in trying to figure out how to use an option. They tell you that you can do it but give no syntax examples and leave out rather important details. To the old guard they are unnecessary since it makes sense by understanding the history and how things work. The new refugees don't want ancient computer history lessons. They don't want to understand the difference between System 7 and Posix and why some stuff use -R and others use -r for recursive. They often don't even want to look at a command line. Most distro documentation is about like man pages. It tells you that yeah you can use a digital camera. Just wait for it to pop up. That's not real useful in troubleshooting if it doesn't. That doesn't help somebody who wants to get accidentally deleted photos off the camera. It states the obvious without giving any real help. Folks turn to documentation mostly for help. Another problem with converting people to Linux is that they are given often some very poor choices in apps to use. For many documentation writers they've used these apps for years, are comfortable with the quirks and are blissfully unaware of windoze equivs for these apps or Linux apps that are equivs for the software people used in windoze. I crucial factor in retaining people who try Linux is the comfort level they feel in Linux. Remember a computer OS is a really big thing. They are literally scared. Afraid they'll break it. They often are slightly technophobic to start with. For years M$ and others have been drumming it into their heads that computers are evil and incomprehensible. Leave the yucky stuff to geeky techs and all will be well. That computers should be like a toaster and require no more thought to use. That's unrealistic, they know it but they've managed to promote the stigma that Linux is technically difficult and Linux documentaion has played right into their hands. It shows only one way of doing things which is often a very poor choice. Most windoze users use WinAmp or something akin to that. In Linux Audacious and XMMS are so close that a windoze user can sit right down and in minutes be playing files. I cannot think of a single distro's documentation that takes that into account. Instead users are pointed at an array of bizzare apps that really do not corespond to commonly used windoze software. The burn process from IE is so buggy few windoze users use it. They use software like Nero. Which happens to have an equiv called K3b which would leave them right at home in burning a CD. I have a very good rate of retention in people I convert to Linux and actively convert people. The key to this is making them comfortable in Linux and the key to that is giving them max functionality with as small a learning curve as possible. A second big selling factor is just how many ways you can do something. I often show them several ways till they start looking glazed from all the choices or they see one they just light up on and love. I might hate that particuler app but who cares. It's THEIR computer. If that's the software they like and using that keeps them in Linux then I've done something good. That is why I came to the Fedora docs project. Fedora is the distro I use and one of the best to start new people converting to Linux on. The problems I see with the project start with the complexity to actually write something. First nobody knows what needs written. 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. 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. Topics I personally think should be covered are. A variety of music players representing classes of music players (ie XMMS style, Jukebox style, Album organization). Then link to different project pages where they can learn more about each. Ripping music. Doesn't have to get format specific. Just a quickie on ABCDE, Lame for command line, GRIP and other GUI rippers. Organization software, taggers, editors, converters. In other words what you can do with a ripped file after it's ripped. Doing this would show the power of Linux. Provide meaningful links to answers to common problems. It would be informitive but not take ages to write and maintain as most of it would be pointing to project docs to give readers the details. In my opinion the red tape surrounding docs leaves them so devoid of content that I personally feel like writing them will not be all that helpful to anybody. This robs me of the desire to write. Instead I've focused on other work I can do for Linux projects. There are 100 places I could start at about scarcity of documentation. A number of places I could contribute. But I feel that the scope itself is so limited that many of these are just out of scope. For example if I contributed on the burner page, I would want to write at least short blurbs about ISO tools, different types of burner software availible. Links so readers could look and choose the software that best fit them. Utilities for dealing with ISO files. A great example. Long ago I used to burn from the command line. K3b changed that. There are however occasions I'd love too but the command line cdrecord tools either had a different syntax or were broken in Fedora last time I tried. Wouldn't hurt to put a short doc on burning from a command line. Another impediment is the access control. I never could edit wiki content. Maybe my ID finally got straitened out, maybe it didn't. I heard other users complain of same thing on this list. So the two docs I did write never got submitted. I pasted one in frustration into the list. Got good constructive criticism on many parts on others I felt the scope limitations were going to limit my ability to write meaningful documentation. The other which was probably more in line with the kind of docs being asked for I never could submit. I tried for weeks. Exchanged emails trying to find the right person to ask about getting my rights corrected. Finally just gave up. Second do we really want people editing content directly? Shouldn't that go through a review before being placed out there? So why not have a submission process? Submit it for peer review, corrections, additions. This means no more fumbling in the dark trying to figure out how to add content or getting frustrated when your account isn't given sufficient rights. People tend to feel slighted when that happens. I'm sure no slight is intended. I've seen no malice on this list toward people. No cliqueism or people feeling above others. Folks seem quite friendly and very interested in doing a good job. 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. 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. Once they've gotten their first doc written and submitted most users will be pretty self sufficient. They can after a few docs in turn serve as ast mentors on other new writers and eventually get forced kicking and screaming into admin roles. Anyway that's my 2 cents. I personally would like to see far more covered. See support for real life usage. See better help for windoze refugees. See a streamlining of the induction process. I still feel very much an outsider with this project, a heratic even. So maybe I just wasted everybodies time but thought I'd make an attempt before I unsubscribe and move on completely to other projects instead. Drac unsigned remote heratic/lunitic. On 8/5/07, Karsten Wade <kwade(a)redhat.com&gt; wrote:

On Mon, 2007-08-06 at 07:51 -0500, Dan Smith 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. Anyone can get an account and edit this page: http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Photos Account creation really isn't that hard, and helpful people are everywhere. http://fedoraproject.org/wiki/DocsProject/Tasks 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. 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". 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. [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"? 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'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. [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. 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. 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. - Karsten -- Karsten Wade ^ Fedora Documentation Project Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.fedorapeople.org | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

On Wed, 2007-08-15 at 14:14 -0500, Dan Smith 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. 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. :) [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. 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. 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. [...] 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. 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. 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. 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. 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] Agreed that this is an impression that I hear. Glad it is obvious that we are trying to make it better, eh? :) Right, well, until it is perceived as unneeded red tape. :) 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 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

On 8/15/07, Karsten Wade <kwade(a)redhat.com&gt; wrote: Your welcome. I've always been rather outspoken :) So I'm good for something at least :) 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 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] 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 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 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 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 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. 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 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. 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 That sounds fair to me. 1. Document one application of every type that can appear in a default 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 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 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. 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

On Wed, 2007-08-15 at 18:10 -0500, Dan Smith wrote: 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. :) 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". There is a long-standing request to get /home as a default partition. Meanwhile, we document around it. 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. 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. Each content type (writing, audio, video, etc.) could use its own stand-alone guide. In the meantime ... :) 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. 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.) 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. 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 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. 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. Can you start this ... :) ... and this? 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. 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. Why not just ask the user to load the application and look at it? 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. 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. 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 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Test case services quick rough draft. Shows support for KDE, Gnome and command line. I have not spell checked this or run it through a grammar checker or done any proofing of any sort on it. Just a quick example that took me about 15 minutes to write. The screenshots are meant to be embedded in the document but will be attachments with this email. Services/daemons are programs that perform useful functions on your system but are not normally started by the user. MySQL for example runs normally as a service. You don't launch MySQL every time you need to connect to the database it is normally always running once you configure it unless you manually shut it down. Services not only start or don't start at boot time. They can be turned on, off or restarted without restarting the machine. Services can also run only at certain run levels. Run levels are various states the machine can exist in. There are only two run levels most Linux users are likely to see. Run level 5 which is today the default for most systems. That is a fully graphically enabled environment. The other is run level 3 which is typically used for trouble shooting and low level system driver installation. In general it is best to turn off any service you are not using. Leaving a service you do not use running is taking a chance there will be a vulnerability in that software which you are not using. For example with Fedora Bluetooth is enabled by default. If you are not using Bluetooth there is no reason to keep the service running. Until recently ISDN ran by default. If you do not use ISDN to connect to the net there isn't any reason to have it installed much less running. If you are unsure about what a service does there are several ways to find out. The GUI service menus often have descriptions. If you from a command line use man service name it will produce documentation about many services. In general it is best to leave it running if you are not sure if you'll need the service or what that service does. To configure your services In KDE click on the Fedora icon in the bottom left corner. You should see Administration up at the top. If you do not install the KDE admin tools from either Yum or a yum GUI such as yum extender or kyum. In Gnome click on System In both KDE and Gnome Click on administration select Server settings then select services. You will be asked for the root password. Then you will see a screen like this. (screenshot kdeservices1.png) By clicking on a service you will get a description of that service and it's status. Services without a check mark are not started at run time. To prevent a service from running at start up uncheck the box next to it. To enable a service at start up check the box. To stop a service select it then click on the stop button. In this example I started the denyhosts service. (screenshot kdeservices2.png) The on demand services tab is for services that are loaded when a client program calls them. Amanda for example is a backup system. It only runs when an Amanda client talks to the system. (screenshot kdeservices3.png) To save the new configuration click on the save button. If you do not do this the services you schedule/unscheduled to start at run time will not be changed. If you click on the revert button it erases all the changes you have made. You can also configure services from the command line using chkconfig. Open a term window. su - to root. Make sure to use the - so that you have root's path and environment variables set up. The basic usage of chkconfig is. To list services chkconfig --list This will produce a screen similer to this. (screenshot chkconfig1.png) To disable a service use chkconfig --level 2345 sendmail off for example to turn sendmail off on run levels 2,3,4 and 5. To turn sendmail on you'd use for run levels 3 and 5 chkconfig --level 35 sendmail on To see other chkconfig options use man chkconfig. To manually turn a service off, restart or turn one on from the command line use the service command. As root. service sendmail restart would restart the sendmail service. (screencap cserv1.png) In the screen capture you see an example of stopping a service that failed. In this case because the service was already stopped. You will also see an example of starting NFS. Notice that not just NFS started. 3 other services started automatically when NFS started. Many services are like this. There is one final way to edit services. It is highly recomended that you use the chkconfig or GUI tools to modify services as well as the service command. To stop a service you can use PS to aquire it's PID and then stop the PID using the kill command. To modify what run time level and stop or start you would have to edit the /etc/rc files. rc rc1.d/ rc3.d/ rc5.d/ rc.d/ rc.sysinit rc0.d/ rc2.d/ rc4.d/ rc6.d/ rc.local Each dir corresponds with the run time level. So to edit a service for run time level 5 you would modify the corresponding file in the /etc/rc5.d/ dir. This is not recommended for any but very experienced users. On rare occasions you will have to modify these files to change default behavior. Generally you will never have to directly touch these files.

On Wed, 2007-08-15 at 16:11 -0700, Karsten Wade wrote: Forgot to actually attach them; this is a better place: http://quaid.fedorapeople.org/drop/services-draft.txt http://quaid.fedorapeople.org/drop/services-draft-kwade_edit.txt http://quaid.fedorapeople.org/drop/services-draft.kwade.patch - Karsten -- Karsten Wade ^ Fedora Documentation Project Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.fedorapeople.org | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\