Review of Jose Armando Garcia Sancio's std.log

[H. S. Teoh]

On Tue, Mar 06, 2012 at 03:52:56PM -0800, Jose Armando Garcia wrote:
> On Tue, Mar 6, 2012 at 3:27 PM, Andrej Mitrovic
> <andrej.mitrovich at gmail.com> wrote:
> > On 3/7/12, Jose Armando Garcia <jsancio at gmail.com> wrote:
> >> http://jsancio.github.com/phobos/phobos/std_log.html#fileNamePrefixes
> >
> > That was what I was looking for but I didn't find it at first. I think
> > that info about what the defaults are
> > ([program].[hostname].[user].[severity].log.[datetime].[pid]) might be
> > useful somewhere at the top. But that's just my 2 cents..
> 
> Yeah. I am not terribly happy how ddoc and dlang.org organizes the
> documentation. I have been thinking of duplicating a lot of the
> documentation to the top but I have two main objections that are
> holding back. 1. document duplication and 2. overloading the user with
> information. I would like the top of the document with enough
> information and example for the regular user to just start logging.
> They can later come back and read the whole thing when they want to
> configure and tweak things. Thoughts?
[...]

I don't like the current state of dlang.org docs either. There is little
or no intro paragraph to explain what on earth the module is used for or
why you should bother reading the rest of the page for the next hour or
so. It also doesn't give any motivating examples (I'm thinking of
std.range here) why this module is useful.

I think a good intro is a must to good documentation. Include some code
snippets to show typical usage of the module. How to change common
settings. Some explanation of why the user might find the module
helpful. It's OK to duplicate some docs here, within reason. It should
also be concise without being uninformative.

For example (from std.range):

	This module defines the notion of range (by the membership tests
	isInputRange, isForwardRange, isBidirectionalRange,
	isRandomAccessRange), range capability tests (such as hasLength
	or hasSlicing), and a few useful range incarnations.

is concise, but not very informative. Why should the user care what a
range is anyway? No explanation is given. Something like this may be a
beginning to better documentation:

	This module defines the notion of a range. Ranges generalize the
	concept of arrays, lists, or anything that involves sequential
	access. This abstraction enables the same set of algorithms (see
	std.algorithm) to be used with a vast variety of different
	concrete types. For example, a linear search algorithm such as
	std.find works not just for arrays, but for linked-lists, input
	files, incoming network data, etc..

	This module defines several templates (<!--insert list
	here-->)for testing whether a given object is a range, and what
	kind of range it is.

	It also lets you construct new ranges out of existing ranges.
	For example, retro lets you access a bidirectional range in
	reverse, cycle creates a range that is an endless repetition of
	the original range. ...

	...

Basically, you're writing an overview to the module, so highlight its
main components, give some insight into why it's useful, etc., so that
the user can make sense of the long list of declarations that follow.

As it stands, std.range's page consists of a giant list of range-related
declarations that gives no hint to the user as to how they all fit
together. You basically have to wade through it until it somehow all
"clicks" together. That is poor documentation. The overview should give
some general categories of stuff that's found in the module (e.g. range
tests, constructing new ranges, etc., as I've tried to do above in my
one-shot attempt to improve std.range's docs). Include some examples of
really clever stuff that you can do with the help of the module. Such
examples are usually a very good way to get the user up-to-speed with
what the module has to offer.


T

-- 
What doesn't kill me makes me stranger.