[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

>  - 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.


> 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

> 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: