[OpenAFS-Doc] Forwarded documentation rant

Sun, 18 Apr 2010 23:57:07 +0100

This is a cryptographically signed message in MIME format.

--------------ms030007070007040904020908
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Jason:

Thank you for sharing this discussion with the community.
It is my hope that the author is currently reading this
thread.  As the author has noticed, yourself, Simon, Russ,
Booker and many others have put a significant amount of
time into the improvement of the documentation.  As you
are aware but perhaps the author isn't, when IBM gave us
their IBM AFS documentation we received raw HTML and not
the sources that produced it.  It took many years and
many attempts to convert the documentation from the html
into a source form (including consistent formatting and
indexing) that could be used by contributors to submit
changes.  All of the documentation that we have is now
in DocBook format and the man pages are in Perl POD format.
The content that is found on http://docs.openafs.org/ is
generated automatically by the build system.  For Windows,
the build system even generates indexed Windows HTML Help
files.

It has only been in the 18 months that the XML sources
have been available in this easy to edit form.  It has
been my hope that with the improved source format availability
that a broader range of users and administrators would
contribute to the depth, breadth, and usability of the
available documentation.

In most cases, the content or a somewhat out of date
version of the content is available.  The www.openafs.org
frame does have explicit links to the OpenAFS Documentation,
the Man Pages, the Wiki, and the Workshops pages.  The search
field is a customized Google Search that explicitly searches
all of the documentation, the man pages, the wiki, and the
mailing list archives.  If the author has suggestions for
how these links should be displayed or additional info that
should be included on the docs.openafs.org home page, s/he
is welcome to submit suggestions but even better would be
patches to the web site.  All of the content of the web
site and the documentation is maintained in git and submissions
are managed using http://gerrit.openafs.org/.

I believe the request for a Concept of Operations section is
covered by http://docs.openafs.org/AdminGuide/ch01.html#HDRWQ6.
The Kerberos v5 content and aklog is handled by the recent
submissions by Booker Bense to update the UserGuide and
QuickStartGuide for UNIX.  This isn't to say there isn't more
to be done.  There absolutely is.  The best individuals to
write that content are the system administrators who most
recently had to learn it.  Asking developers to write user
documentation does not produce good user documentation.
The developers have taken to the time to produce a format that
can be edited.  Now is the time for the user and system admins
to step forward to improve the content and make it answer the
questions that other users and admins like themselves have every
day.

Jeffrey Altman

On 4/17/2010 9:56 PM, Jason Edgecombe wrote:
> Hi Everyone,
>
> I wanted to share a user's rant about what is still needed in the
> documentation. The first inclusion is a follow-up email. the second
> inclusion is the original message.  Names and identifying info has
> been removed to protect the ranter. I'm working to help this person
> become a contributor. The rant has a lot of value for what is missing.
> Where else should these ideas be recorded?
>
> Sincerely,
> Jason
>
> -------- Original Message --------(edited to remove some information)
> Jason,
>
> After sending you my long tome, I just today had a look at
> docs.openafs.org.  It's looking much better than when I looked a
> couple of years ago.  Someone's done a lot of work.
>
>
> -------- Original Message --------(edited to remove some information)
>
> Jason,
>
> As a perpetual OpenAFS newbie, it's always bothered me how well hidden
> the basic documentation is from those who don't know where to look.
> If you could add to your boilerplate a beginners link, that would be a
> good thing.
>
> Then of course, you need to build a worthy object of that link.  I see
> you and Russ have a "better documentation" project.  The documents
> tend to rapidly dive into details without much context.  Does such a
> thing exist as a Concept of Operations ("conops") document for
> OpenAFS?  I don't even know where to find the man pages on
> openafs.org, short of downloading a source image and pulling the man
> directory.  The conops document would provide the context so a reader
> would know which man page to read when.  Although a large proportion
> of your audience is programmers who take a lot of common software
> engineering knowledge for granted, some of us are junior sysadmins who
> get thrown, ready or not, into AFS.
>
> An outline somewhere of skills needed for various roles in the care
> and feeding of a cell would be useful.  One of the big disappointments
> to the AFS community about Milicchio's book was that it focused on
> basic skills, rather than documenting the esoterica.  Alas, what
> basics he did document for us beginners were rapidly obsolete because
> he made such a tight cookbook that as versions progress, all the
> details change.  His book would have been much stronger as an outline
> of skills, concepts and pointers for where to find the current
> particulars.
>
> I imagine a document, which starts after the sales pitch, with some of
> the fundamental concepts of setting up a cell, something like:  To
> start up a cell, you need a network which conveys UDP ports
> 7000-7003(?), a working time server and time synchronization scheme.
> You probably also want some sort of DNS.  You need a candidate AFS
> server, your first of several, running some form of Unix, with [a list
> of particular packages].  If you happen to be running a Debian derived
> Linux (Ubuntu, et. al.), you can get the right AFS stuff at..., and
> public face of those packages is often Russ Allbery.  For Redhat
> family distributions (RHEL, Centos,...), the AFS packaging can be
> found at... Other popular operating systems for AFS servers include
> Solaris, AIX, ...  Note that the AFS servers running on one operating
> system are entirely compatible with AFS clients and other servers
> running on other operating systems.
>
> OpenAFS, the currently supported version of AFS, depends on Kerberos,
> an authentication system developed at MIT.  You have a choice between
> the current version from MIT, krb5, or a compatible version from
> Sweden, Heimdal.  There are differences in interface and methodology,
> but they are technically mostly interchangeable.  Unless you happen to
> know a particular unique feature you want from one or the other, your
> decision will likely be guided by international politics and
> encryption export laws.
>
> Whether you use a pre-compiled version of OpenAFS or compile your own
> is likely a decision based on your skills, comfort level and time
> available.  Be warned that without some software diagnostic skills,
> setting up and maintaining a cell can be an overwhelming challenge.
> Here is a list of tools most of the developers will want you to
> understand how to use when you need their help to fix a problem...  A
> brief list is included in the release notes, but you would do well to
> start with Wikipedia pages for these debugging and analysis tools and
> then become a bit familiar with their use.
>
> In the general daily experience of users of an established AFS system,
> they see a large multi-organization shared file system represented as
> /afs.  Below that level, are organizations, and below those depends on
> the needs of each organization.  To have privileges in the system
> beyond reading completely public documents, one must get an AFS token
> via Kerberos.  In an organization which has set up a single sign-on
> system, the user picks up the token (ticket) in the process of initial
> login.  Otherwise, the user must use the local tool(s) for
> authenticating to a Kerberos server, by which the user will gain
> credentials for the desired AFS cell, often klog followed by aklog.  A
> cell is an administrative zone within AFS, sometimes representing a
> large organization and sometimes a group within an organization.  Cell
> names often mirror names in domain name service.  Note that Kerberos
> and AFS talk about tickets and tokens, a similar concept, each
> representing an identity within that system.  Kerberos tickets are
> used to acquire AFS tokens, by which AFS knows which user is which and
> what privileges have been assigned that user.  Privileges can vary by
> directory, and can include the abilities to read files, write (change)
> files, delete files, administer directory permissions...
>
> I could go on, but I hope you get my drift.  I've hoped for a really
> high level introduction to administering AFS, mostly so I can see what
> skills I need to go out and learn; I don't know enough to write and
> contribute it myself.  I use your newsletter and the mailing list to
> educate myself, in a scattershot way, and to gauge whether OpenAFS is
> a mature enough product to make sense for a person of limited software
> engineering maturity, trying to get through life with a liberal arts
> degree in computer science and no programming experience.  I've gotten
> a lot from the mailing list by osmosis, but I still think the level of
> my questions would annoy most people on the mailing lists, no matter
> how genuine my efforts.  I am overwhelmed with all the stuff I'm aware
> I don't know.  I'd at least appreciate guidance on what, where and how
> to learn the skills to truly join the community, beyond the role of
> village idiot.
>
> My day job role is ***********,
> trying to constantly justify the work of a bunch of bright software
> engineers and to triage misunderstandings among managers.  I have yet
> to be able to demonstrate to them why we would benefit as a group by
> adopting AFS for our own operations, never mind that I'm somehow
> supposed to efficiently share files with them across the country, as
> well as have the ability to share files in a secure way with our
> customer.  Most of my personal daily production is in spreadsheets,
> emails and meetings, interrupted by an occasional phone call if really
> necessary.  In my dreams, I'm a competent system administrator, with
> lots of practice systems lying around the house.  My other interest at
> the moment is learning virtualization systems, so I can clean house of
> all those dinosaurs.  Progress is exceedingly slow.
>
>
>
> On Tue, Apr 13, 2010 at 9:14 PM, Jason Edgecombe
> <jason@rampaginggeek.com> wrote:
>> If you could change anything about the newsletter, what would you
>> change?
>
>
> _______________________________________________
> OpenAFS-doc mailing list
> OpenAFS-doc@openafs.org
> https://lists.openafs.org/mailman/listinfo/openafs-doc

--------------ms030007070007040904020908
Content-Type: application/pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
Content-Description: S/MIME Cryptographic Signature

MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIJeTCC
AxcwggKAoAMCAQICEAMF9RTCGOz151fTpHLih+cwDQYJKoZIhvcNAQEFBQAwYjELMAkGA1UE
BhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMT
I1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBMB4XDTA5MDgyODA0MDExOVoX
DTEwMDgyODA0MDExOVowczEPMA0GA1UEBBMGQWx0bWFuMRUwEwYDVQQqEwxKZWZmcmV5IEVy
aWMxHDAaBgNVBAMTE0plZmZyZXkgRXJpYyBBbHRtYW4xKzApBgkqhkiG9w0BCQEWHGphbHRt
YW5Ac2VjdXJlLWVuZHBvaW50cy5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDZNscYIvF6xzGSAfa/QUIqiElyn0EUxL2b86eKiYqe91bj0gLr/MJoErLnb+OmokxqSAH6
y0zlFqSbiFwgNM8m69K6m/6YO+x3+5zBc+u6snwTWMEWygnhx3rQ/lMhoQOgArraL+/k9aWL
kNdaXQKk6EZVW9pfV2A4Lk4DoZGFjY8tJRWWDLlFkYnxDuIEpLYwJpwakv3QHOaq/G8KW0iE
jVhVzPobuZzwD2tuepY/bsClwqxz/gfAEpUvAn/lYTqnoT7RYljZlCIdbrgcG/HSYMxAy1Zp
Yh8Fx+9cqsG8O4nqo26SVfYZvrYhh8m6OqW8Vakdt7vBLCTa/QhIdJ4hAgMBAAGjOTA3MCcG
A1UdEQQgMB6BHGphbHRtYW5Ac2VjdXJlLWVuZHBvaW50cy5jb20wDAYDVR0TAQH/BAIwADAN
BgkqhkiG9w0BAQUFAAOBgQBvbvJNXUJ4atv1CExIe0J38jZqoEUTttkXOfCDT9e3mSmVboOK
ifHDyLZQC4qSsCUfP7vdwAXjKtjak22HbfX2sEKCUgtnOkxRqXMM2V/NW/ESNVQZF0TO7L/Z
cW3icObO9FIZCSmgFMt2Al7VPfMQmaJNlqu9SLmXSwbRFJ5b4zCCAxcwggKAoAMCAQICEAMF
9RTCGOz151fTpHLih+cwDQYJKoZIhvcNAQEFBQAwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoT
HFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25h
bCBGcmVlbWFpbCBJc3N1aW5nIENBMB4XDTA5MDgyODA0MDExOVoXDTEwMDgyODA0MDExOVow
czEPMA0GA1UEBBMGQWx0bWFuMRUwEwYDVQQqEwxKZWZmcmV5IEVyaWMxHDAaBgNVBAMTE0pl
ZmZyZXkgRXJpYyBBbHRtYW4xKzApBgkqhkiG9w0BCQEWHGphbHRtYW5Ac2VjdXJlLWVuZHBv
aW50cy5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZNscYIvF6xzGSAfa/
QUIqiElyn0EUxL2b86eKiYqe91bj0gLr/MJoErLnb+OmokxqSAH6y0zlFqSbiFwgNM8m69K6
m/6YO+x3+5zBc+u6snwTWMEWygnhx3rQ/lMhoQOgArraL+/k9aWLkNdaXQKk6EZVW9pfV2A4
Lk4DoZGFjY8tJRWWDLlFkYnxDuIEpLYwJpwakv3QHOaq/G8KW0iEjVhVzPobuZzwD2tuepY/
bsClwqxz/gfAEpUvAn/lYTqnoT7RYljZlCIdbrgcG/HSYMxAy1ZpYh8Fx+9cqsG8O4nqo26S
VfYZvrYhh8m6OqW8Vakdt7vBLCTa/QhIdJ4hAgMBAAGjOTA3MCcGA1UdEQQgMB6BHGphbHRt
YW5Ac2VjdXJlLWVuZHBvaW50cy5jb20wDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQUFAAOB
gQBvbvJNXUJ4atv1CExIe0J38jZqoEUTttkXOfCDT9e3mSmVboOKifHDyLZQC4qSsCUfP7vd
wAXjKtjak22HbfX2sEKCUgtnOkxRqXMM2V/NW/ESNVQZF0TO7L/ZcW3icObO9FIZCSmgFMt2
Al7VPfMQmaJNlqu9SLmXSwbRFJ5b4zCCAz8wggKooAMCAQICAQ0wDQYJKoZIhvcNAQEFBQAw
gdExCzAJBgNVBAYTAlpBMRUwEwYDVQQIEwxXZXN0ZXJuIENhcGUxEjAQBgNVBAcTCUNhcGUg
VG93bjEaMBgGA1UEChMRVGhhd3RlIENvbnN1bHRpbmcxKDAmBgNVBAsTH0NlcnRpZmljYXRp
b24gU2VydmljZXMgRGl2aXNpb24xJDAiBgNVBAMTG1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFp
bCBDQTErMCkGCSqGSIb3DQEJARYccGVyc29uYWwtZnJlZW1haWxAdGhhd3RlLmNvbTAeFw0w
MzA3MTcwMDAwMDBaFw0xMzA3MTYyMzU5NTlaMGIxCzAJBgNVBAYTAlpBMSUwIwYDVQQKExxU
aGF3dGUgQ29uc3VsdGluZyAoUHR5KSBMdGQuMSwwKgYDVQQDEyNUaGF3dGUgUGVyc29uYWwg
RnJlZW1haWwgSXNzdWluZyBDQTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxKY8VXNV
+065yplaHmjAdQRwnd/p/6Me7L3N9VvyGna9fww6YfK/Uc4B1OVQCjDXAmNaLIkVcI7dyfAr
hVqqP3FWy688Cwfn8R+RNiQqE88r1fOCdz0Dviv+uxg+B79AgAJk16emu59l0cUqVIUPSAR/
p7bRPGEEQB5kGXJgt/sCAwEAAaOBlDCBkTASBgNVHRMBAf8ECDAGAQH/AgEAMEMGA1UdHwQ8
MDowOKA2oDSGMmh0dHA6Ly9jcmwudGhhd3RlLmNvbS9UaGF3dGVQZXJzb25hbEZyZWVtYWls
Q0EuY3JsMAsGA1UdDwQEAwIBBjApBgNVHREEIjAgpB4wHDEaMBgGA1UEAxMRUHJpdmF0ZUxh
YmVsMi0xMzgwDQYJKoZIhvcNAQEFBQADgYEASIzRUIPqCy7MDaNmrGcPf6+svsIXoUOWlJ1/
TCG4+DYfqi2fNi/A9BxQIJNwPP2t4WFiw9k6GX6EsZkbAMUaC4J0niVQlGLH2ydxVyWN3amc
OY6MIE9lX5Xa9/eH1sYITq726jTlEBpbNU1341YheILcIRk13iSx0x1G/11fZU8xggNxMIID
bQIBATB2MGIxCzAJBgNVBAYTAlpBMSUwIwYDVQQKExxUaGF3dGUgQ29uc3VsdGluZyAoUHR5
KSBMdGQuMSwwKgYDVQQDEyNUaGF3dGUgUGVyc29uYWwgRnJlZW1haWwgSXNzdWluZyBDQQIQ
AwX1FMIY7PXnV9OkcuKH5zAJBgUrDgMCGgUAoIIB0DAYBgkqhkiG9w0BCQMxCwYJKoZIhvcN
AQcBMBwGCSqGSIb3DQEJBTEPFw0xMDA0MTgyMjU3MDdaMCMGCSqGSIb3DQEJBDEWBBTrr3N7
GirggU3Ssi4Vn+I/H0Oz1DBfBgkqhkiG9w0BCQ8xUjBQMAsGCWCGSAFlAwQBAjAKBggqhkiG
9w0DBzAOBggqhkiG9w0DAgICAIAwDQYIKoZIhvcNAwICAUAwBwYFKw4DAgcwDQYIKoZIhvcN
AwICASgwgYUGCSsGAQQBgjcQBDF4MHYwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0
ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVl
bWFpbCBJc3N1aW5nIENBAhADBfUUwhjs9edX06Ry4ofnMIGHBgsqhkiG9w0BCRACCzF4oHYw
YjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4x
LDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAhADBfUUwhjs
9edX06Ry4ofnMA0GCSqGSIb3DQEBAQUABIIBAHo/MtF9wkUciPGm9KpjD47txtb5VGmryUVA
HigdkOOfzFeYbZdQOrGUQfEX598RMHXrGo0rHukl2buYpgIa/SPTMsU9vTJTNQt3VhzfGOmv
j8f+0sVbZ9e+2GsQkGuvM+IUCZemw0jGJiuKRb3yW9MyYYZOoFiSv3JVkMY1OIYsqYSBanhz
D16JSPZ5Q61PoqGfX8C+yNvUuzoLiKrmP/Y1Vt8yUz9Sa3SqbzlL2qZAQdbmsvQIHV0CREXE
y/a/obRFOmEY4jeHvHETMNni9j7KfwPaiEJNWq+rrN7pzOSqxn2puAnmXpzuwTfAoxOfeksU
2FyW1qFtWPWkVZP29T4AAAAAAAA=
--------------ms030007070007040904020908--