darren at younghome.com
Fri Sep 8 09:13:06 PDT 2000
All agreed, I think the first step is to lay this out in a structure that
we can debate on. ALFS desperately needs a definition section so everyone
can be on the same page. The other thing that needs to be set forth first
in any documentation project is the languare used to create the
documentation, the standards for coding and the basic structure. I think
we should follow Gerard's method in the LFS SGML source with small
documentation "pods" dealing with a specifc subjet. These small "pods" can
be dealts out as tasks to people to create. Integration of them into the
final document can be done at any time, and they can be layed out in any
Before anyone can start documenting what's going on, they need to have a
clear explanation of how to do it. The standards that are agreed to, the
tools and their versions that should be used and the basic skeleton (what
you just mentioned)..
The reference section should probabl be started soon as well, since people
will want to get their hands on the tools and start contributing.
Here's my proposal:
1) Set documentation standards. Language, formats, coding conventions. I
believe we should stay as close to the LFS book as possible so it may be
included if necessary.
2) Develop basic skeleton of content.
3) Define the order in which areas need to be developed
4) Code it
5) Approve it
6) Integrate it
We have to keep in mind that we are here to support the ALFS effort and
anything that can contribute to that quickly should be done
first. Everyone seems to be a bit confused as to the layers of ALFS and
the definitions that are used (profile, profiler, etc.). I think that
should be the first area to be developed.
My .02 cents worth...
On Fri, 8 Sep 2000, Jason Gurtz wrote:
> Hi all,
> I've been trying to think what form the documentation should take. At a
> minimum it will discribe how to use the ALFS "system." As I see it, three
> chapters could support the minimum. The first would be a chapter describing
> the front end, describing basic use of the interface, hot keys, commands,
> the order in whch things happen, etc... The second, a (long?) chapter on the
> profile system, could be split into 2 sub-chapters. One would go into the
> "base" profile that comes with the system, describing what it gives you at
> the end, what the profiler does with the profile, and maybe things that
> often get changed by the user. The second part would be a reference on the
> sytatctical details of writing a profile, and hints as to how to write a
> profile "from scratch" (tm). The third chapter would cover the compiler or
> "Back-end" of the system.
> There is also, of course, the obligatory credits section, and a suggested
> reading and where to find out more section. Additionaly, sections could be
> added, covering: History, or where did this come from, standards the system
> follows, primers on XML, and troubleshooting, including basics of the
> complilation process with hints as to possible causes of some of the error
> messages that can crop up.
> I'm probably missing some things. Feedback is always appreciated! :)
> ~Jason (BTW I'm flake on #LFS)
> | Jason at tommyk.com |
darren at younghome.com
"Sometimes one pays most for the things one gets for nothing"
More information about the alfs-discuss