Admin Guide / Accounts - call for feedback

[Vladimir Kosovac]

Paul W. Frields wrote:
> 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 ;-)

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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 251 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061213/0b1f0b5d/attachment.sig>