Admin Guide / Accounts - call for feedback
Tommy Reynolds
Tommy.Reynolds at MegaCoder.com
Tue Dec 12 13:36:07 UTC 2006
Uttered "Paul W. Frields" <stickster at gmail.com>, 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.
Cheers
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061212/9ee69675/attachment.sig>
More information about the fedora-docs-list
mailing list