Pierre Labastie wrote:
Hi,
I'd like to know what the followers of this list think about jhalfs
documentation, and what would be their advises for improving it.
Personally, I have not much idea of how documentation should be done, and
apart from text improvement (there is room for that), I am happy with the
"README" format (supplemented by help in menus). But some of you may have
more clever ideas. So please speak up.
Right now you have README.* files. That's OK. I'd remove README.HLFS and
add INSTALL.
For INSTALL, I'd not assume that the user unpacks the directory of the
tarball in it's final running location. That is different from all of the
LFS and BLFS packages we deal with all the time. It may be as simple as
unpacking and then moving the entire directory:
$ tar -xf jhalfs-2.x.tar.xz
$ cd jhalfs-2.x
$ ls
INSTALL jhalfs
And say that the program can be run from the current jhalfs directory or
moved to the user's choice for a final location, e.g. 'mv jhalfs ~'
The prerequisites should be listed int he INSTALL file.
With the above changes, the README can be made a little smaller, but is
basically OK. I'd also move the BLFS_TOOL SUPPORT section to README.BLFS
with one exception. It should explain that using the BLFS tool is a three
step process: Installing the tool, running the BLFS tool, and building
the selected BLFS packages. All the details of that should be in the
INSTALL.BLFS file.
These are just suggestions for your consideration. What you have works,
but for first time users may not be quite basic enough to start.
-- Beuce
--
http://lists.linuxfromscratch.org/listinfo/alfs-discuss
FAQ: http://www.linuxfromscratch.org/faq/
Unsubscribe: See the above information page
