On 6/25/06, Nathan Kroenert <[EMAIL PROTECTED]> wrote:
Just some random thoughts on this...
One of the initial design criteria of ZFS is that it's simple. If it's
not, that was a bug...
If we need tutorials to use the zfs commands, has something missed the
mark?
When new ways of doing things are introduced, it is often times
desirable to have a way to express it in a different context, a
different format, etc. Creating pools, file systems, snapshots,
clones, etc. may be simple to those that have spent a lot of time
thinking about it. Now put yourself in the mindset of a junior level
admin that is qualified only because the course completion certificate
on his cube wall says he is.
Now, looking forward a bit, where does the ZFS integration with zones
documentation belong? How about real world replication strategies
with zfs send/receive, including appropriate utility scripts?
Converting UFS root to ZFS root?
If the information that is needed to do the work is NOT in the man
pages, perhaps we could look to address that...
All of the information is in man pages. Often times, stringing man
pages together to bigger concepts is too hard. Hence the general fear
of man pages by UNIX newbies and some oldbies.
Personal example: I learned lots of systems programming from man
pages, looking through header files, and looking at others' code.
Then one day I was in the book store and found a book call "Advanced
Programming in the UNIX Environment" by W. Richard Stevens (RIP). I
sat down in the middle of the isle for what must have been 3 - 5 hours
reading so much of what I had learned through so much effort. At that
point, most of what I was reading was review or stuff I didn't care
about. However, there were a few "ah-ha!" moments scattered in there.
All the while, I was thinking how much it would have helped me to
have that book when I first started learning.
Personally, I'd prefer to read a manpage than scour the web for a
tutorial that may or may not be current.
While not ZFS, I can offer a current example. Brendan Gregg has a
great page (http://users.tpg.com.au/adsln4yb/zones.html) on
configuring zones, including setting up resources pools, and
management strategies. I suspect that a future update will talk about
using zones with ZFS. If I need to know a particular option to
zoneadm or zonecfg, man is great. When I was first learning how to
get zones and resource controls to play together, Brendan's page was a
good overview of my options that cannot be adequately conveyed in man
pages, if I can find the right one.
hm... man zfs_tutorial? :)
I think this is the case of there is an admin guide and a man page. I
see a wiki as serving the purpose of an admin guide in an Open Source
environment. Wiki's are really simple to learn to use (from an
authoring standpoint) and have the right barrier to entry to encourage
those that aren't coders to contribute to development of
documentation. If the way to make changes to documentation requires a
source tree checkout, learning docbook, etc. most would-be authors or
editors will be discouraged. Else, I guess it just winds up in a
bunch of blogs that are really hard to find.
Mike
--
Mike Gerdts
http://mgerdts.blogspot.com/
_______________________________________________
zfs-discuss mailing list
zfs-discuss@opensolaris.org
http://mail.opensolaris.org/mailman/listinfo/zfs-discuss
