On Wed, 2007-08-15 at 18:10 -0500, Dan Smith wrote: > > > On 8/15/07, Karsten Wade <kwade@xxxxxxxxxx> wrote: > ... all those 50-100 of tabs I have open have to be reopened. You're like me in that regard (last session was 8 windows, 87 tabs.) Do you use Session Manager? It is a real hero: https://addons.mozilla.org/en-US/firefox/addon/2324 Tab Mix Plus is great in combination with Session Manager: https://addons.mozilla.org/en-US/firefox/addon/1122 I didn't switch from Galeon until Firefox extensions had all these features. :) > > [snip content about best of breed] > > Sorry, without Paul's comment to compare it to, I'm > guessing. I presume > you mean his comments that we want to document the default > installed > applications before we branch into non-defaults also available > for > Fedora. My comment above is that the reason we don't have the > default > camera stuff well covered is a lack of resources. Whoever is > working on > the User Guide decides what are the priorities for > coverage. If there > isn't a person or time to get to cameras, it is not in that > guide. > > > As for default install that I'm not as sure of. I have never used the > default install. Probably a good candidate for virtualizing and trying it out. We have to assume that the average user who installs from one of the live spin media is going to not ask for more than is installed automatically. That automatic set of packages on the GNOME and KDE live spins are the "default". > The partitioning scheme is for starters unworkable for me. There is a long-standing request to get /home as a default partition. Meanwhile, we document around it. > ... Why not cover file managers since it is a crucial part of how any > OS works? Since they are the part of the user interface many people > see the most of. ... It would be informative and after all isn't it > our job to distribute information? I chose this snippage because I think it is a good representative question. Way back when people asked "Why is Fedora Docs focused only on short tutorials and how-tos?" The answer is that it is a full-time PITA to maintain a real guide, like one of the ones you find here: http://www.redhat.com/docs/manuals/enterprise/ It *is* possible for a community to do that level of work, but it needs to build up to that. In the intervening years, we have built/are building infrastructure that supports that level of writing. We can really take on work from anyone, any group size, any amount of content. "Bring it on," someone once said in another context. What I get from your thoughts on this topic is that you think it is easy to do the depth and breadth of coverage that you suggest. I think you underestimate the challenges of making Fedora quality documentation out of these ideas. > I posted a quick example of documenting KDE, Gnome and command line in > the same set of documentation. That was a good example of how to interweave. It was good depth, with it getting richer the farther down you go. I think it was good for the Admin Guide, appropriate to reference from the User Guide. For the docs you see on redhat.com/docs, figure that it is eight hours of work to produce every page of the content. There are industry standards we could reference, and they are fairly accurate. About four hours to update a page, and two hours to maintain a page (check that it doesn't need further updates.) This time includes everything from research, testing, QA, editing, and re-writing. My point is that when we focus on one technology choice (the default) over others, we cut the time for those pages. Maybe not exactly in half or quarter. Perhaps third. Oh, and there is a metric to apply to the translation side. Where you add in additional applications, you increase the difficulty of translating and resulting QA, etc. > Which brings up text editing. Each content type (writing, audio, video, etc.) could use its own stand-alone guide. In the meantime ... :) > Still some docs is better than no docs wouldn't you say? To get "some docs" we need to either have a broad coverage that is not very deep (just defaults, by spin type), or have deep coverage of fewer areas. > Agreed so why not cover the commonly used stuff at least at a high > level and provide a link for users to do their own footwork to do > detailed comparisons? I don't think we're in disagreement here. The only difference of opinion may be on how much work this requires of *other* contributors. Each person is not of the same skill, experience, time, or attention level as each other. > > Speaking of machines not using X. Many of the documentation guides > make no provision for command line equivs. Not documents I write! In fact, skipping all the screenshot junk allows you spend more time on quality CLI content. I think, across Fedora, we have been mixed, but certainly tried to be CLI aware. Red Hat docs afaik always cover both methods, which is why they are so resource intensive (see above rough formulas.) > The default is a pretty varied animal even if you use only the > server/desktop/whatever else default installs. I view default as what > is normally contained on the Fedora install CDs or in the Fedora > official repositories. OK, but we as a project need to have a proper definition of default. The one we use in Fedora Docs happens to match what e.g. Release Engineering means when they say "default". At least, afaik. > In all that time the only users I ever lost back to windoze were ones > using default Fedora installs. You have identified a niche/audience we need to address. We can do that. Maybe there is a sane way to do that. * docs.fedoraproject.org/doc-name/ => focus on defaults per spin, broad and not too deep, or deep and not too broad; proper workflow to get content published, good publishing tools for self-service * fedoraproject.org/wiki => all the content that is not in the above docs, maintained at a quicker pace (fewer style or editing requirements, more wiki/community style), more "rawhide" than "released"; pull content from here for every release to bundle into docs.fp.o > Most of us have technical backgrounds. Not really the experience here; it is quite mixed in terms of the folks who have self-intro'd. But anyway, we do expect people to do basic research, even if they are just learning how; after all, we all have to get started somehow. > I'm just not seeing a large time investment in supporting KDE and > Gnome and potentially XFCE. Second some docs are better than none and > if nobody is around or willing to contribute the other desktop's > section then so be it. Maybe we're just not vocal enough. We have a serious active-contributor shortage in this project. Refer to the meeting summary from yesterday: http://www.redhat.com/archives/fedora-docs-list/2007-August/msg00048.html I'm personally beating my head against the wall trying to figure out how to do it better. I don't have much time, either. I need folks like _you_ to get on the Wiki and start writing stuff like the FAQ, etc. > This sounds like a good place to review the task list. I've noticed > quite a few missing areas such as text processing. I'd suggest taking > one section a week and building a task list from a concencious on the > list. Can you start this ... > The same approach. If you'd like I can start with the admin list and > build a topic list using this group to start discussions on what > topics and where to put what sub topics. :) ... and this? > Ok, I was following convention by providing lots of screen shots. It is not really Fedora convention. Just like we inherit RPM from Red Hat-based distros, so do we have a love for DocBook XML and a dislike of too many screenshots. Diagrams are cool. Especially SVG ones, doubly-especially when someone hacks PO (i18n) support into SVG files. > They can be a bit bulky and unfortunately change as the interface > changes, but can also say quite a bit. In the screen shots in the > sample services doc I sent. Would any be useful in the final doc? I honestly never looked at them. I looked to see if the content needed any images, and it didn't. It is also visually shorter without images inline. Much snappier read. I just recreated the commands to get content to paste into the {{{code}}} blocks. > In the case of file managers a screen shot can say what would take > pages to say. Why not just ask the user to load the application and look at it? > In fact a screen shot, a line or two and a link to the project would > probably be the best way to handle the file managers section. Users > could in minutes narrow down their favorites, install them and be up > and going. This is a different use case. These sound like canonical pages for each application, a sort of product page. Like Freshmeat, or Amazon pages. That is a good idea, I'd expect that is being worked on as part of the Online Desktop, and so we can probably inherit those/use the upstream URLs. > > 1. Document one application of every type that can appear in a > default > GNOME install. > 2. Document one application of every type that can appear in a > default > KDE install. > 3. Document additional applications that are > popular/best-of-breed but > aren't necessarily the default in one of the upstream desktop > environments. > > In many cases though there are only trivial differences in usage but > big differences in looks, speed, key bindings and such. This is an interesting POV. Teach the concept and then give a quick overview of the ways to accomplish it. Like fishing and handling rod and tackle. It can work, I just think it takes more rigor (time, resources) than we can expect of most unpaid contributors. YMMV. > > > ... Reread the welcome letter to the latest guy to join the list. He > was pointed at the translation section but the Wiki Account creation > you put into this post for example was missing. So were quite a few > things he'll need to get started. Truth, and to be honest, I did that on purpose. He came to translate, and I had to presume he had found L10N/Join or he wouldn't know to self-intro using the provided template. He also mentioned an interest in doing more technical/content contributing; my reply was intended to elicit a reply from him. Maybe I should have piled on URLs in addition? Regardless, a single FAQ with a million such links would be a great place to start and a nice single URL to hand over for all cases. - Karsten -- Karsten Wade ^ Fedora Documentation Project Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.fedorapeople.org | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
