Re: Admin Guide / Accounts - call for feedback

On Tue, 2006-12-12 at 05:36 -0800, Tommy Reynolds wrote: > Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, 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 ;-)

> 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.