On Tue, 2009-06-09 at 23:04 -0400, Scott Robbins wrote: > On Tue, Jun 09, 2009 at 07:24:06PM -0700, Adam Williamson wrote: > > On Tue, 2009-06-09 at 21:15 -0400, Scott Robbins wrote: > > > > > > Ideally it would be best to direct people to the appropriate bit of the > > > > release notes: > > > > > > > > http://docs.fedoraproject.org/release-notes/f11/en-US/sect-Release_Notes-File_Systems.html > > > > > > > > > > They'll miss it. Even if they get that far through the release notes, > > > it has to boldly state--you CAN'T INSTALL THE LIVE CD ON ONE PARTITION. > > Yes, as I said, it's not a very good note. > > It's not a bad note, it's just that again, the sort of folks who are > having issues aren't the folks who will grasp what it actually means. That's what makes it a bad note, IMHO. :) It's very rare that you can't write a good note which both fully and correctly describes the issue, and explains its impact in terms that novice users can work with. That's certainly possible in this case. > > That's not really an accurate characterization, I don't think. I'd say > > more that Fedora is working on _developing the tools_ that make > > designing a click and click and you're done distro possible, but Fedora > > is not that distro. (RHEL is, on the desktop side.) > > You've made an eloquent explanation of that before (and I have referred > people on the forums to it), but I'm not sure it's inaccurate. Like it I don't think we really need to carry on with this bit, as it's a side-track and not very relevant. > > I disagree. Mandriva truly is a click-and-click-and-you're-done > > distribution, but most of its users are now accustomed to reading the > > release notes and errata for each release, because we made a concerted > > effort over a couple of years to use these documents as canonical > > sources, make sure everything was covered in them (and not split up > > across multiple itty bitty sources with varying official status), and > > link to them all the time. > > > So that's something to consider, but then, the release notes will have > to be clearer. That seems ungrateful, knowing how you and others (I've > already mentioned Rahul, but if I start trying to name everyone, I'll > leave too many out) labor over them, but if the project page is going to > imply it's for everyone, then they have to be written in a more obvious > form. > > Not being really familiar with Mandriva, I don't know how well this > worked, or if your forums, like Fedora's, were swamped with each new > release with "I'm running into X, Y, and Z." My thought is to try and > nip that in the bud. That's not exactly realistic - whatever you do, there'll always be people who don't read the documentation. My ideal vision is a world in which X, Y and Z are all documented in the same place, and when someone asks about them in the forum, many people could reply "oh, you can read about that at http://path.to.release.notes/X!";, rather than "oh, you can read about X at http://path.to.release.notes/X , Y at http://some.other.site/Y , and Z, well, we sort of wrote about it in this sticky thread, but also you need to know yadda yadda yadda..." I don't really labour over the release notes that much. I contributed, oh, four or five bits this cycle, most of them very late and they didn't all get in. To be honest I was still in a bit of a Mandriva mindset, where the release notes never freeze for translation, are carried on the Wiki, and are constantly edited after release. Fedora works to a more traditional system where the notes freeze for translations quite a while before release and are essentially static once they're 'finished'. I may have to try and do something about that ;) (maniacal laughter) The release notes are mostly written by the docs team. In many ways they do a great job - the Fedora release notes are much longer and more exhaustive than the MDV ones I was involved with tended to be, which were mostly written by me, a week before release, based on the bits I vaguely remembered having changed during that six month cycle (what's that you say? Notes? Notes are for the weak.) I do think, though, that they work mostly from a "documenting technical changes" perspective, whereas we're looking at things from a bit more of a "practical problem solving" perspective, so there may be things we'd want in there that the main docs team might not usually think of, and differences in phrasing. The obvious answer to this is that we all join the docs team, roll up our sleeves and get working on the F12 notes a lot earlier, and maybe propose a couple of changes to the process. Which I intend to do. :) > > > The days of a one line reply to such a complaint on the forums of, RTFM, > > > have, for better or worse, become a thing of the past. > > > > That's really not what I was talking about. > > I'm sorry, I didn't mean to imply that you were. If it came out that > way, and rereading it, I see how it easily could have, I most humbly > apologize. Hopefully you realize how I (and many others) appreciate > your efforts. No problem, don't worry about it. > View it as an engineering > > challenge, if you like. You don't duplicate code all over the place and > > spread it around disparate places, you group it all neatly into one > > library and use that library everywhere. Ditto with release-relevant > > information: come up with a coherent story on where it should be, train > > all the relevant people to contribute to those sources, and refer to > > those sources consistently. > > An excellent point, and valid. One problem, for me, again speaking > selfishly.... I only have so much time in the day. Many times, I don't > feel the official documentation is adequate, and again, to save myself > time, I'll post something, either on my own home pages or the > forums--often, my own home pages, simply because it's easier to remember > a link to that than to find a forum post again and again. What we have here is another engineering problem: we don't have a canonical location for release notes that turn up after the release. Well, technically the official release notes can get updated somehow, I believe, but I don't think that process is used much in practice. This is something else we should discuss with the docs team and try to come up with an improvement to the process for. > So, let's say I disagree with the clarity of the document we have > mentioned, about the file systems. I want to put, be careful if you > download the live CD, etc., etc. I edit the notes. Someone disagrees > and changes it back. (Something similar happened with the thing about > ctl+alt+backspace with X.) Now, I've wasted time, whether I'm right or > wrong. I also have the guilt of having wasted the time of whoever > changed it. > > If I feel strongly, then, more time is spent arguing the point with the > changer. > > So for me, personally, that's an issue. I'm not employed by RH, Fedora, > or CentOS. It's going to be quicker for me to to post it on my pages or > the fora. This is not necessarily a good thing, but it's not a good > thing for everyone to automatically assume *my* documentation is the > best, either. :) What I think would improve this is to be actively involved with the docs team; they have a mailing list and an IRC channel and stuff, and they all seem to be nice people. ;) I idle in their IRC channel and I intend to formally join the group and follow the mailing list soon. I think that would give a better experience - people would then be more likely to seek you out to discuss changing something you'd written, rather than just doing it wholesale. I expect they rewrite things contributed by non-team-members as a matter of course. Being employed by RH (Fedora and CentOS don't really employ people...) doesn't mean anything much. The docs team isn't made up entirely of RH staff, and the contribution process works the same way for RH and non-RH people. I don't get any special sauce, I write my contributions into the Wiki beats like anyone else. > However, I do have experience in writing for beginners, and have the > additional motivation that if I'm out sick, and our Windows Admin, who > teaches mixed martial arts as a hobby and has arms the size of my legs, > finds it unclear, I'm going to hear about it--fear's a powerful > motivator. :) > > Your answer is actually the best, but so far, I've seen too many gaps > (for the beginner) in the official documentation, and the one time I > tried to fill in the gaps, it was changed back. Well, as Rahul said, that doesn't seem to have been exactly what happened, though it was of course unfortunate. But I'm pretty sure we could do this better in future. > One major problem though, that will always be with us, is that > even in the instance you mention, Mandriva, you say the "users gradually > learned." But what about the distro hoppers, such as the type I > mention, who are just trying it out of curiosity and aren't going to go > through pages of release notes? That's a genuine problem, I just think it's not enough of one to be worth discussing problems on the download page. The problem with that is, where do you draw the line? There's lots of issues that could potentially be critical to someone or other, if you're not careful you wind up with a 50% semi-dupe of the Common Issues page stuffed into the download area. urgh. I think it's safest just to draw the line at having any bugs mentioned on there, it's not the page's function. > Thanks for listening, and as always, for your input. Thank you too. -- Adam Williamson Fedora QA Community Monkey IRC: adamw | Fedora Talk: adamwill AT fedoraproject DOT org http://www.happyassassin.net -- fedora-test-list mailing list fedora-test-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-test-list
