Paul W. Frields wrote: > On Tue, 2006-12-12 at 05:36 -0800, Tommy Reynolds wrote: >> Uttered "Paul W. Frields" <stickster@xxxxxxxxx>, spake thus: >> >>> On Mon, 2006-12-11 at 12:52 +0530, Rahul Sundaram wrote: >>>> Vladimir Kosovac wrote: >>>>> I have couple of sandboxed pages ready for your review/input at: >>>>> http://fedoraproject.org/wiki/wiki/VladimirKosovac/StylingPage/WorkPage >>>> For example, if I am doing web services administration, I would expect >>>> to learn about system-config-httpd in that section along with the Apache >>>> configuration details. >>> That's an excellent point Rahul makes -- that our documentation should >>> be largely task-based. Relevant material should be lumped together >>> where possible and logical. >> Agree emphatically. >> >> What I detest is "feature-oriented" documentation that mostly walks >> around the buttons and menus of a GUI, or is an elaborated bullet >> list of each separate feature (even if the elaboration runs to pages >> or chapters). I'm as guilty as anyone about doing this ("My name >> is Tommy. Chorus: Hi, Tommy!") but I'm recovering ;-) Am I understanding these suggestions well if I then say that tables on the intro page are redundant. To me, they look just like the stuff we want to avoid - feature listing for GUI tools - although more obscure. Scrap them, then? | vnk | >> Every button / menu / feature / asset was designed into the program to >> provide a service, with a reason behind that decision. Document the >> problem solved by the feature, et. al., and not the implementation. >> Answer the question of "how do I foo", not the question "what do all >> these buttons mean?"; then the "what are all these dials and switches" >> question becomes moot. >> >> So, instead of this: >> >> o The FILE menu has an EXIT button. >> >> I'd prefer to see: >> >> o When you are finished, click the FILE/EXIT button to >> save all your work and to gracefully terminate the >> program. >> >> Just my $0.02e+27, YMMV. > > Yessirree! To harp on something (yet again), note how important this > makes defining your audience and their core knowledge, skills, and > abilities: Without that thatinformation, you can't tell what your > audience can't do without in terms of instruction. > >
Attachment:
signature.asc
Description: OpenPGP digital signature
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
