Re: [i10n] Installation Manual Updates (long)
On Mon, May 03, 2004 at 07:30:04PM +0200, Frans Pop wrote:
> Hello David,
>
> First of all: great that you are taking an interest!
Thank you, I appreciate it.
> I am working on a Dutch translation and have been in contact with Miroslav
> Kure over some general issues (like the restructuring of Ch 6 committed
> yesterday).
Fantastic! I haven't seen Chapter 6 yet, but I'll take a look and save
messing around with it for last. I'm sure it's in great shape now, thank
you!
> In my mind the chapters needing most work are the ones that are most outdated:
> - - 2 System requirements
> - - 3 Before installing
> - - 4 Obtaining system installation media
> - - 5 Booting the installation system
> - - 8 Next steps
> - - Appendix A
>
> Personally I think the current structure of chapters 6 (Using D-I) and 7
> (Booting into new system, or better Base configuration) is basically OK;
> these mainly need filling out. These chapters should form the core of the
> manual.
Agreed. Chapter 1 needs serious adjustment, and Chapter 2 and 3 need to
be re-organized and combined to some degree. Chapter 4 needs lots of
filling out. Unfortunately, these are the only ones I've gone through
and mapped out what I want to do so far, so I can't speak for what
follows as of yet.
> I agree some things could be dropped altogether (like the info on how to set
> up a RARP, BOOTP or DHCP server).
Definitely.
> What I miss most at the moment is a clear introduction of d-i outlining the
> stages in the installation process, the different installation levels
> (default, DEBCONF_PRIORITY=medium, expert), the main different installation
> methods (CD/DVD, floppy, network, ...) and how these will be covered in the
> manual. I think this should go before the current chapter 2.
This is a good idea, although I'm tempted to make a latter chapter with
either a reference for this sort of thing (probably in a question and
answer format) or simply an "Expert Install" chapter. That'll be decided
later.
> Anyway, we should try to make it clear to readers in what situations which
> parts of the process will be skipped or performed 'invisibly' and where
> problems can be solved by choosing another PRIORITY level (without
> necessarily explaining all details).
Yes, although I think spelling out certain things isn't worthwhile.
There's no point in making them read about certain aspects that "just
work". This will be a balancing act, and I'll know how to describe it
better once I actually start editing.
> I believe the intention of Miroslav is to focus the manual on default
> installation and move exotic things or detailed information (like hardware -
> I mean make & model, not architecture - specific stuff) to appendices, like
> he has done for Partitioning.
Agreed, which is how I want to proceed.
> It would be great if you could give us an outline of how you visualize the
> structure of the manual.
My overall goal, and model, is to bring our manual up to par with the
Gentoo installation guide, which is continally lauded by users of
multiple distros. I've read it through a few times, and can say I'm
definitely impressed by its structure and organization, as well as the
way they balance the iformation the new user will need with what they
don't need to know. Given that their install is far more difficult than
ours currently is, this is quite a feat. I've listed the main features
that I want to borrow from their docs in my restructuring plan, which
I'll send to the list once it goes beyond chapter 4.
> For translators I guess most important is to make very clear when existing
> text is moved, because it would be easy to mistake major moves for text that
> has not been translated yet.
> So if you could report moves with something like 'moved section <title> within
> AAA/foo.xml' or 'moved section <title> from AAA/foo.xml to BBB/bar.xml' that
> would be great. Of course, this is less important if complete documents are
> moved.
All right, will do.
> Also it would be great if you could separate restructuring from editing. It
> can be very hard to look for changes in content in text that has been moved
> as well. The main problem is, how much time to leave between the two (I think
> at least enough to give an opportunity to update the local SVN to the
> situation after the restructure and before the edit).
> This is of course not very important if you plan a major rewrite of existing
> text because in that case a fresh translation is probably easier anyway.
The problem is that the organization of the current manual is a bit like
patchwork. There's a lot of information that needs to be moved around to
make the document more coherent. Sure, I can ignore this, but the manual
is incredibly dated and has suffered for it. It needs some real work. We
can discuss this is more detail once I finish my plan.
> I will have a fair amount of time available myself starting next week, so I
> could do reviews and help planning changes if you like. My main problem is
> that my experience with Debian is limited to i386.
> I was planning to do some work on the English texts in chapters 6 and 7 and
> maybe the introduction I mentioned as I feel most comfortable with those.
Great, thank you. My experience is limited to i386 as well, although
like you said, leaving arch-specific stuff to later is fine. I'm more
worried about simply cleaning the manual up and reorganizing it to bring
it up to standards.
> Please keep the list posted on what subjects you start on to avoid two people
> working on the same subject at the same time (as much as is possible in a
> project like d-i :-).
Will do. I'm stuck in finals right now, so my time over the next week
will be limited, but I'll try and at least finish my plan and perhaps
start editing Chapter 1 or 2 soon.
- David Nusinow
Reply to: