An insider view of some future addition to the PAM documentation

Okay, so today I got the definitive answer: the disk is no good: some of the files I was able to recover from lost+found disappeared again, and that included not only Python libraries (thanks to solar’s tinderbox I was able to fix that at least temporarily), but also libstdc++, and some of the glibc includes, that made it impossible to actually fix the installation.

For now I am “stuck” with the MacBook Pro, which is nice as I can still work on my job stuff (like for instance trying to write yet another article that will be rejected by a magazine, or some kind of software I can actually sell to someone, for specific tasks), but I can’t really help with most of the software I resumed maintaining for Gentoo in the past weeks (PAM, Proaudio, …).

Anyway, this doesn’t stop me from at least work on some of the PAM documentation companions I was working on, in particular, the following diagram is supposed to explain the interaction between the different pieces of a software during authentication:

PAM Component Interactions

Please tell me what you think, and yes I know it’s far from being a proper explanation, I’m planning on adding a more detailed diagram with the detailed timeline, following UML sequence diagrams style. This way you can get both a generic view for newbies, and a more detailed one for those who actually know how to read an UML diagram.

I think this is something I should have done before, and I have to thank Mike to suggesting this to me. Graphical companions to technical documentation is something important, but it’s not quite that easy; while UML provides good basis to documenting design and implementation, there are very few people and projects who actually use them, and publish them, before implementation, and after implementation it’s quite silly to start writing these things down, or is it?

Quite sometimes this might come more useful for people touching the code afterward, like new developers, or people somehow interested in a fork. While some people might see this as a good reason not to document the design and interface, to avoid people “stealing” their code, or design, there are two considerations to do: the first is that Free Software projects are about sharing code and experience, and documentation is part of it; the latter is that even when the developers are new developers for the same project, it is often likely that the new developers have little or no contact with the original developers after a few years, this is my case in xine. Let alone the cases where you’re “forced” to make a fork because the original developers disappeared.

Anyway, I’ll try to make good use of the time I’m stuck on the laptop, so I won’t waste it.. but first, I want to take a few days off, as what should have been my week of vacation last week was ruined by the data entry job (that completed today.. if I’m lucky, considering who I worked for, I’ll have my money three months for now).

Too bad that most of the anime series I was planning to see are on the currently-unavailable disks of Enterprise 🙁