John S. Gage wrote:
>
...clip
> The Linux world can probably get away with undocumented software, but we
> cannot, should not, and will not(?).
...clip
Wait a minute. The Linux Documentation Project is, in my judgment, one of
the things that made the Linux phenomenon possible.
Now, it is true that there is quite a bit of undocumented code in the
open-source arena; and more problematically, there is quite a bit of poorly
commented code out there. But it is NOT a standard of the "Linux world" to
fail to document software.
This is not a rant; it just happens that I know Michael K. Johnson, the first
originator of the Linux Documentation Project, so I know how well this can
work when it's done right, and I have seen how high the standards are, never
mind that no one gets fired if they're violated (their code gets ignored).
He has promised me a brief essay on how we should proceed with our own
Medical OpenEMR documentation project.
In the meantime, while we are waiting for Swami to speak, look at
the GNOME documentation project: go to
http://developer.gnome.org/
and click on bonsai -- it's in the top toolbar --
then click on the only link on the next page,
Main Bonsai Repository View page.
Now you will be in the Repository Directory.
This is the top-level directory for GNOME projects.
To see the structure of a simple area, click on GGAD, (left column, fourth item).
To see the structure of an area with multiple contributors, click on gnome-libs
(second column, way down: they're in alphabetical order).
This project uses CVS software (Current Versioning System).
If we are going to have a viable project, we need NOW to begin planning and
organizing the documentation process; this is determined by two somewhat
disparate needs: end-user functionality and designer requirements.
We have been seeing a lot of useful and productive debate
about tools and languages; we also need to set infrastructure,
and need a TOOLMASTER for this purpose.
If our infrastructure is not well laid out, we will end up chaotically tripping
over ourselves.
More later.
Cordially,
Dan Johnson md
