On Sun, 2008-05-11 at 15:21 -0400, Bill Davidsen wrote: > Aaron Konstam wrote: > > <snip> > >> Documentation? NM has been around since FC6, and people seem to keep > >> saying that the documentation is being worked on. At least on FC9beta it > >> really didn't work, ignored the hardwire, and brought the WiFi up on a > >> random open AP. I live between an apartment building and a college, > >> there are enough open APs available to choose. > >> nations of the wicked." - from Slashdot > >> > > http://live.gnome.org/DarrenAlbers/NetworkManagerFAQ > > > > > > http://live.gnome.org/NetworkManager > > > I appreciate that you're trying to be helpful, but the FAQ does > hand-waving instead of giving useful answers. > > Example > > Q: "How does NetworkManager select which wireless network to connect to?" > > A: (part1) NM only attempts to automatically connect to networks you > have previously told it to connect to. [not the case, it picked one] > > (part2) If NM isn't connecting to the network you want, try to force it > to connect to the network you wish to be connected,... [If I knew how to > force it I wouldn't be reading the FAQ, now, would I?] > > (part3) In version 0.6.6 and later there is a profile editor that can be > used to add/remove networks. [Again, effort saved by not bothering to > tell the user HOW to get that tool running] > > > All it would take is a hyperlink at each point where the reader is told > to do something unfamiliar. However, not only is there no hyperlink, the > index points to a single sentence on doing this, "For version 0.6.6 or > later Use the Network Profile editor to remove unwanted networks." Do I > have to tell you that there doesn't appear to be a link in the table of > contents which describes the Network Profile Editor and how one accesses it? > > > I have written documentation for GE, IBM, SBC and technical articles for > national magazines, I've dealt with enough editors to know that this FAQ > is simply not well written for the target audience. And if I knew the > topic I would offer to make changes, but I don't. But as people are > forced to switch from known easy to use tools like > system-config-network, a lot of people are going to be unhappy trying to > learn a complex tool of limited capabilities. Agreed. The insufferable complacency of a man page that assures the reader that NM aims to Just Work, when quite often it Just Doesn't, is going to come home to roost unless someone writes some real documentation. The man page for NetworkManager(8) even refers to a mythical NetworkManagerDispatcher(8) page which doesn't exist, while the nm-applet(1) page -- presumably the page intended for end users -- says precisely nothing. It's noteworthy that neither of the two existing man pages even refers to the FAQ or indeed to the NM website. A basic system utility such as NM needs at minimum a description of 1) what it does, 2) how it does it, 3) how you can tell if it's doing it, and 4) what might be wrong if it isn't doing it. poc -- fedora-list mailing list fedora-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-list
