From seth at userprimary.net  Wed Oct  7 05:40:01 2009
From: seth at userprimary.net (Seth Falcon)
Date: Tue, 6 Oct 2009 20:40:01 -0700
Subject: [Rd] how to document stuff most users don't want to see
In-Reply-To: <8ed68eed0910061209u62013017uafd13e4db15d6c3a@mail.gmail.com>
References: <mailman.17.1254736805.9993.r-devel@r-project.org>
	<20091005175041.GB31394@stat.umn.edu>
	<77EB52C6DD32BA4D87471DCD70C8D70001E5FD32@NA-PA-VBE03.na.tibco.com>
	<4ACA428C.80102@prodsyse.com> <4ACAF775.8030708@pburns.seanet.com>
	<8ed68eed0910061209u62013017uafd13e4db15d6c3a@mail.gmail.com>
Message-ID: <20091007034001.GF47890@orange.local>

Writing good documentation is hard.  I can appreciate the desire to
find technological solutions that improve documentation.  However, the
benefit of a help system that allows for varying degrees of verbosity
is very likely to be overshadowed by the additional complexity imposed
on the help system.

Users would need to learn how to tune the help system.  Developers
would need to learn and follow the system of variable verbosity.  This
time would be better spent by developers simply improving the
documentation and by users by simply reading the improved
documentation.

My $0.02.

+ seth

-- 
Seth Falcon | @sfalcon | http://userprimary.net/user



[Rd] how to document stuff most users don't want to see
Seth Falcon