Re: [i10n] Installation Manual Updates
On Sat, May 08, 2004 at 07:34:08PM +0200, Miroslav Kure wrote:
> On Fri, May 07, 2004 at 10:36:45PM -0400, David Nusinow wrote:
> > Ok, I've finished my general plan for editing up the d-i manual. It's a
> > bit vague at parts, mainly because I won't know how to organize or
> > rewrite parts until I actually start the writing. Since it's fairly
> > large, I posted it to
> > http://www.tufts.edu/~dnusin01/d-i_manual_plan.txt
>
> Some of these ideas are also in doc/manual/TODO and doc/manual/README,
> so don't forget to keep them in sync. (Maybe we could merge them?)
Yes, I'll merge the info in to the TODO before beginning actual editing.
> Chapter 3:
> - installing X could go to some appendix or somewhere around "Prompts
> during package installation"
Yes, although I'd rather have it in the main body of the install manual.
It's very very important for a large number of users, and its easily the
question I hear most often in support forums. The way gentoo's manual
handles configuration info is to give you basic configuration for things
like X in the installation manual and the rest in their soon-to-be
configuration guide, which I think is a very wise model to follow.
> - no need to describe how to backup. If they can't handle it, they
> shouldn't install an operating system.
I disagree. This is harsh and unnecessary, and only harms potential
users.
> - to answer your questions about sections 3.5, 3.6: they are there
> logically. (Chap1 talks about Debian, Chap2 outlines some hardware
> issues, Chap3 makes the necessary preparation and a part of this is
> setting up BIOS and making free space for Debian before
> installation. The rest of the chapters deal with installer...)
Well, again I think 3.5 should probably be deleted, since FIPS is
archaic. And I feel like the organization for 3.6 doesn't make sense. I
think a stepwise, procedural organziation rather than a topical one is
good for the manual.
> Chapter 4: nothing one can argue with.
Great!
> Chapter 5:
> - of course booting from USB key is there (5.1.4)
Yes, I forgot to delete that from my list. Thanks.
> - you want to delete "booting from a DOS partition", but on the other
> hand you want to describe bits for W98 in previous chapters? A bit
> inconsistent.
Good point. You're right, it should stay in.
> Chapter 6:
> - this got a bit renewed last week, sorry :-)
Yeah, I haven't built the newest versions to have a look at the revised
version. I'll do that when I get closer to it.
> Chapter 7:
> - some of the stuff already happened in the move to Chap6
Great to hear.
> Chapter 8:
> - Compiling a new kernel may be needed to make your own boot floppy
> with otherwise unsupported hardware. Maybe move to appendix?
Agreed. An appendix is a good place for it.
> Appendix A:
> - where would you move "The Directory tree"? It somehow belongs to
> the partitioning.
I'd put it with the main body of partioning information in Chapter 6.
That way people have it on hand when they're reading about using
partman.
> Appendix B:
> - B1: Device names here are the "real" Linux names (/dev/hda1). Device
> names from Appendix A should be the names used by installer
> (/dev/lun0/disc0/partition0), so don't remove that.
All right, that's fine.
> Appendix C:
> - Administrivia is (and has been) just that. End of story.
Again, I think a real title would be better. And it does need an intro
paragraph describing what's in the section.
> Previous list of suggestions may seem too big and a bit harsh, but
> from my point of view I'm heart-bounded with some sections you want to
> delete, since I've been translating the manual for way too long
> (potato, woody, now sarge ...). During the time I've seen many great
> suggestions but close-to-zero action.
I'm not suggesting things, I'm planning them. We have a new installer
and it's time for a new manual. The old one is, quite frankly, not in
such great shape. I hear too many bad things about it, and remember my
own bad experience in using it as a newbie, to want to leave it as is.
And, quite frankly, when I compare it to the docs from other distros
it really doesn't hold up. I'm sorry to tear apart your baby, but I have
a degree in English and I was trained to cast a harsh eye when editing
in order to improve on things. The goal really is only to improve what's
there, not to destroy for the sake of destruction.
> One other thought: If you'll have a look on the doc/manual/README,
> there is a mention about quick install guide. Meanwhile Joey wrote
> INSTALLATION-HOWTO - what about using it (after converting to docbook
> and some cleaning) in a manual:
>
> Part 1: Installation for Impatient
> Part 2: The Manual Proper
>
> This way we don't need to simplicize things too much and can save some
> boring editing?
I thought about the HOWTO quite a bit, and talked with both Joey and Rob
Weir about writing a proper basic d-i walkthrough based on it. However,
I think it's more important to get the manual itself in good shape. I
don't plan on oversimplifying, but rather focusing the information
properly and clarifying obscure points. There's some definite
reorganization the basic structure that could serve the manual as well.
I don't plan on hiding details at all (which I hope is apparent in my
edits) but rather on having them explained in a clear manner so that the
manual is truly useful to everyone who uses it. I'd like to see the
HOWTO fleshed out as well, and I plan to work with Rob on that soon, but
having the manual available as a reference is more important.
- David Nusinow
Reply to: