Admin Guide / Accounts - call for feedback

[Paul W. Frields]

On Tue, 2006-12-12 at 05:36 -0800, Tommy Reynolds wrote:
> 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.

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.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
       Fedora Project Board: http://fedoraproject.org/wiki/Board
    Fedora Docs Project:  http://fedoraproject.org/wiki/DocsProject
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061212/d416166f/attachment.sig>