Brendan: Thanks for the input - I like your way of differentiating quite well. I'd say based on the definitions you've provided that the docs I was dreaming of were in the How To and Quick Start categories. I don't yet have the kind of technical prowess with Solaris that would make me a good originating author for the type of Cheatsheets you make reference to.
Other List Subscribers: I think I'd like to start by looking at what the community already has covering basic Samba setup. What docs should I be exploring? I'll try to work up a draft based on my own experience and then get feedback on what best practices I should be embracing and where my errors are. Brian G: Is there a wiki in place already where we can collaborate on some of this n00b documentation? I'll be more motivated if I know the community is watching. One of the first things I'd like to post in such a place (if we all want to use a wiki) is a list of proposed How To/Quickstart topics. Blake On 5/3/07, Brendan Gregg - Sun Microsystems <brendan at sun.com> wrote: > > G'Day Folks, > > I hoped to post some examples of "cheatsheets" that I've written in the > past, > but I found it difficult to identify what was and what wasn't a > cheatsheet. > Consider these (they aren't great examples, but should show what I mean), > > > http://www.opensolaris.org/os/community/mdb/tips/mdb-cheatsheet.pdf > > http://www.solarisinternals.com/wiki/index.php/DTrace_Topics_Cheatsheets_Checklists > http://www.solarisinternals.com/wiki/index.php/Zones > > http://www.solarisinternals.com/wiki/index.php/FileBench#Quick_Start > > They are all information dense, and assume experience with the topic. The > first two could be called "cheatsheets" while the last two "quick start > guides". (oh, and Jonathan Adams wrote the mdb cheatsheet - in case you > were wondering!). > > The Sun docs people may already have some good terminology conventions to > use. > The following is a suggestion that springs to mind: > > "Cheatsheets" > focus on content: key commands, options, config files, man pages > the most information dense - suitable for printing > may list commands for common tasks > assumes previous experience with topic > content/examples/description ratio: 5/0/1 > > "Quick Start Guides" > focus on examples: what to type to get started, the generic case > assumes general OS experience > content/examples/description ratio: 1/2/1 > > "How Tos" > focus on different specific tasks: how to do A, how to do B, ... > assumes experience with subject concepts > content/examples/description ratio: 1/2/2 > > "Reference Documentation" > focus on completeness: explains everything > assumes no or little prior knowledge > content/examples/description ratio: 1/1/5 > > Examples for each may be, > > "Cheatsheets" > IP Filter Cheatsheet > -------------------- > Commands, > ipf -Fa -f /etc/ipf/ipf.conf # load rules > ipfstat -ionh # list rules > ipnat -f /etc/ipf/ipnat.conf # load NAT > ipnat -l # list NAT > svcadm enable ipfilter # enable IP Filter > ipfstat, syslog, snoop # ways to debug config > issues > > Files, > /etc/ipf/ipf.conf # firewall ruleset > /etc/ipf/ipnat.conf # NAT ruleset > /usr/share/ipfilter/examples/ # example configs > > Docs, > ipf(1M), ipf(4) # filter docs > ipnat(1M), ipnat(4) # NAT docs > > Firewall Config, > ... key syntax ... > > Quick Start, > 1. # svcadm enable ipfilter > 2. # vi /etc/ipf/ipf.conf > 3. # ipf -Fa -f /etc/ipf/ipf.conf > 4. # ipfstat -ionh > 5. positive testing (what should work, works) > 6. negative testing (what shouldn't work, doesn't) > > (PS - don't actually use this cheatsheet for anything technical - > I'm > just spent 3 minutes writing it so it is probably wrong). > > "Quick Start Guide" > IP Filter QuickStart > -------------------- > Enabling IP Filter on Solaris 10, > > 1. # svcadm enable ipfilter > Enable the ipfilter SMF service. > 1a. If you are on Solaris 10 3/05 through to Solaris 10 xx/xx, the > pfil service needs to be configured as follows. > 1. # vi /etc/ipf/pfil.ap > comment out your interface name > 2. # svcadm restart pfil > to enable the pfil changes > 2. # vi /etc/ipf/ipf.conf > An example ruleset is, > ...etc... > > "How Tos" > Sharing a ZFS filesystem with Samba - Blake > Apache/DNS - Michelle > > "Reference Documentation" > docs.sun.com - sysadmin guides > > ... > > Do these terms make sense? Or do we at least agree that "cheatsheet" could > mean one from a variety of different structured documents? :) > > cheers, > > Brendan > > -- > Brendan > [CA, USA] > -- 'His mind was good, but he only understood one or two things in the whole world - samurai movies and the Macintosh - and he understood them far, far too well.' - Snow Crash -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/docs-discuss/attachments/20070503/86bbeafc/attachment.html>
