Re: Documenation Update and Query
Ross Boylan <RossBoylan@stanfordalumni.org> writes:
> If by high level hacking you mean basic moving the sections around, I
> have not finished with that--this is literally a snapshot of where I
> am now.
Please finish it, at least as a rough cut. We need this in shape
within 24 hours or so for 2.2.13.
> My thought is to organize the files by installation stages, so that
> the subsections (<sect1>) would be
> documentation
> boot files (root/rescue)
> utilities
What is utilities? Oh, like the DOS tools on i386 or something?
> drivers
I don't know why this wouldn't be grouped with boot files. At least
should be before utils, which are optional.
> base
> beyond
Beyond?
> This is partly to make it easy for people to see what they need if
> they switch from diskettes to anything else.
Are you considering subgroupings based on media? I would suppose not.
> I remain skeptical that this section needs to provide links to each
> individual file. First, it does make it more likely the documentation
> will be out of sync with the files.
This isn't a big deal. We've already done most of the work to sync
the docs with the reality, and things won't be changing very often at
this stage.
> Second, do we really think anyone
> is going to download 14 bootfloppies by selectively clicking on html
> links, when they can go to the right direct and just pull off the
> files they need?
You'd be suprised.
> Third, there is the unresolved formatting problem.
I think this may be resolved by ardo by using, in <taglist>,
<tag>
file1
<tag>
file2
...
Let me worry about that.
> In the interests of not rocking the boat I was planning to leave all
> the links in (despite what I just said).
Yes -- do not touch that please!
> In the interest of
> formatting, I was going to use generic headings, and put the files in
> the item text. Apparently the formatting problem (the failure to
> wrap) is only a problem for titles/headings.
Please do *not* do so.
> Aside from the editorial question of what to do, actually doing it
> will require a lot of cut and pasting.
Sounds good.
> The other high level issue the rewrite raises is incorporating
> material on the different flavors and subarch's into the main doc. I
> basically copied the writeup of the different i386 flavors into the
> install manual, but that is not a desirable long term strategy.
It's a start. Documentation by definition involves redundancy.
Remember the purpose of that text is simply to enable folks on i386 to
decide what flavor to try first.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: