Re: speculations to characterize issues for Debian Enterprise
CJ Fearnley <cjf@CJFearnley.com> writes:
> Deciding on the right abstraction level for the documentation is
> difficult. I prefer functional and "operational" classifications (in
> contradistinction with tool-based classifications). Then the
> documentation helps at the design level as well as for implementation.
> For example, one big enterprise category for me would be "Identity and
> Privilege Management". I imagine that a document about that would need
> to start with background on AAA (Authentication, Authorization, and
> Accounting) in broad conceptual terms, then a discussion of the state of
> standardization (RADIUS[1], Diameter[2], OpenID[3], Shibboleth[4],
> NIST's RBAC[5], SAML[6], etc.), then we'd need to document component
> subsystems (PAM[7], Kerberos[8], LDAP[9], etc.), followed by an
> annotated listing of FOSS tools that can address at least part of the
> project (the Debian Wiki's annotated list of control panel software[10]
> might serve as a good model), then a series of HOWTO articles (like
> those at http://www.debian-administration.org/) documenting how others
> have solved the problem which would bring the theory to a concrete form
> usable by practitioners. The only problem I see is that it sounds like
> a large book project.
Yes. :)
I was looking at that and thinking that was an immense amount of work, and
work that could fairly quickly get out of date. I wouldn't want to tackle
trying to maintain it.
My immediate goal is going to be to get our internal documentation
released publicly as a set of documents about how one site solves these
problems, since that documentation I already have to keep up-to-date so I
know it will stay correct. I'm not sure how to organize that into a
broader picture. In order to take advantage of the updates that we
already do for internal documentation, that will mean that what I publish
won't be in a wiki, since I don't have any way of doing bidirectional sync
and I'm not really interested in generating wiki text from our internal
documentation. Instead, it will be static web pages on my site that
anyone can point to (including, of course, a wiki).
That sort of collection of pointers to other people's best practices
documentation would at least be useful, although of course we could go
farther. One of the other things that comes to mind would be a set of
best practice guidelines for writing software which we could point
upstreams to.
I don't like the HOWTO format, personally, although I realize it's useful
for some people. The documentation that I'm working on is more structural
and design documentation, not step-by-step instructions on how to deploy
something.
> Hence it can be readily concluded that I think the current Debian wiki
> page on Enterprise[11] is ... not quite what I have in mind for a good
> Enterprise Debian documentation resource ;)
Yeah, it's a sort of random collection of tips, some of which are fairly
obsolete now.
> Do we have a good wiki resource to build upon?
> Should we put it all in Wikipedia or is wiki.debian.org or another wiki
> more appropriate?
I personally admit to using traditional wikis only grudgingly, since I'm
not fond of the process of editing documents in a web browser, or in an
editor spawned from a web browser. But as mentioned above, I'm not sure
I'll have much time to do things beyond try to release our internal
documentation and comment on the mailing lists, so that's not necessarily
something to take into consideration.
I don't think our goals match Wikipedia's goals.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: