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

Re: Debian Reference

Osamu Aoki wrote:
> On Sat, Sep 24, 2005 at 01:07:48PM +0900, Osamu Aoki wrote:
>>On Wed, Sep 21, 2005 at 12:08:35AM +0100, Antony Gelberg wrote:
>>>Don't use the word Debian where it's redundant.
> Fine.  But this implementation may require whole rewrite. --> Low priority.
>>>Remove historical points, or move to appendix, too confusing.
> Fine.  But this implementation may require whole rewrite.
>   For desription which does not apply on sarge       --> high priority
>   For description which is just not use much anymore --> low priority
>>>Highlight need to know / don't need to know.
> Fine.  But this implementation may require whole rewrite.
>>>Some things too wordy, some too concise.  If a word isnt needed, get it out.
> Fine.  But this implementation may require whole rewrite.
>>>Order should be order of use e.g. fundamentals, install, the boot
>>>process, etc.
> This implementation will require whole rewrite.
> Besides, I think we need to redefine scope.
>   install thingy              --> release note / install guide
>   random bug work around note --> now we should move to wiki.debian.org
>   Pre-requirement:   basic Linux/Unix skill
>   Scope of document: post-installation guide for 2.6 kernel linux system
>   Outline:
>    * Preface
>      - Define terminology and provide pointers to pre-readings
>      - 
>    * Debian package system overview
>      - basic idea of debian package
>      - archive design
>         stable/testing/unstable difference
>    * Installation and upgrade of Debian     (short text with pointer)
>      - Limit contents to minimum
>    * Tutorial
>      - basic unix command line shell guide
>      - guide with mc
>    * Package manupilation commands
>      (Do not recommend mixed distribution system)
>      - Basic tools (explain positioning and layered structures)
>        - tasksel
>        - dpkg
>        - dselect           (state this is depracated)
>        - apt-get/apt-cache (state this use needs to be limited)
>        - aptitude          (preferred)
>        - synaptic
>      - Extra tools
>        - apt pinning
>        - apt-get source
>        - apt-get build-deps
>        - auto-apt, ...
>        - fancy dependency tools
>    * Basic system management
>      - Kernel / module / udev configuration
>      - Network configuration
>      - 
>    * Backup methods (with CD/DVD)
>    * Emergency recovery methods
>    * Application guide
>     Hmmm... this will be too much.  Let's see what you said first.
>>>I know Woody is still supported, but move to appendix?
> I would say that keep minimumalist update to current documentation for
> extreme bug fix and start new XML based document with graphs and tables.
>>>1.5 move to 2.1.2
>>>Point out at start of 2, that the Distribution is made up of Packages
>>>and that there are actually several distributions.
>>>2.1 rename to Distribution.
>>>2.1.1,10,14,15 move to new subtopic, 2.1.3, Directory layout.  Point out
>>>that this is for advanced users, and apt handles all.
>>>2.1.3-6 move to subtopic of new 2.1.1, Flavours.
>>>2.1.7-9 move to new 2.1.2, Flavour Naming.
>>>2.1.11 remove.
>>>2.1.12 move to where unstable is described. incoming not a distro,
>>>perhaps better explained in 2.2.
>>>2.1.13 move to 2.2.
>>>2.2 rename to Packages.  We talk about package internals too soon.
>>>Should be more top-down.  Start explaining how to search packages.  Then
>>>how to install and remove.
>>>2.2.1 rename to overview, but can stay.
>>>2.2.2 Searching, Installing and removing (when talk about how it knows
>>>what to pull in, refer to Package dependencies).  Chapter 6!
>>>2.2.2,5-10 move to new 2.2.3, All about .deb.  Emphasizekeywords e.g.
>>>2.2.4,11 move to upgrade section
>>>2.2.13 remove?  Kind of covered in NMG.  If stays, move to new 2.2.4,
>>>Building from source and change first bit to apt-get source.
>>>2.2.14 move to new 2.2.4, Building from source.
>>>2.3 One upgrade section is enough.  Filter into chapter 6.
>>>2.4 Can't talk about boot before install.
>>>2.5 Not really a fundamental.  Filter into relevant sections and delete
>>>this one.
>>>2.6 This relates to 2.1, perhaps make 2.1.4 or refer to at start of 2.1.
>>> Could also be incorporated into a What Debian Offers / Why Debian in
>>>bullet points.  We have About Debian on the www, which is severely limited.
>>>2.7 One kernel section is enough.  Filter into chapter 7.
>>Good points.  But when I consider practical aspects of all the
>>secondary works, I really can not do these now.  (Translation....)
> I think that making these extensive changes are still not good enough.
> So why creates too much work.  I think we need to work totally rebumped
> text.  For that, your thoughts are very good base for next version.  But
> we need to make a new XML version.
>>>>Instead, I suggest you to do bug hunting and issue hunting on chapters
>>>>and thinking how all other needs to be reorganized and how that will be
>>>>3. installation hint.  
>>>>  -  how this can be reorganized without duplicating install masnual.
>>>>5. Upgrading distribution
>>>>  - how can this be made distribution independent
>>>>  - avoid overlap with installation and release note.
>>>>6. Package management
>>>>  - Now that aptitude is main tool, we need to carefully update this.
>>>>  - Remove all woody/potato things.
>>>>7. Kernel
>>>>  - Rewite this focusing udev/2.6 management (But who knows best?)
>>>>8. Tips
>>>>  - New installation CD is not easy tool for emergency recover.
>>>>    Suggest bootable CD alternative
>>>>  - im-switch
>>>>  - UTF-8
>>>>Oh, please read some basics of contributing document at:
>>>> http://qref.sourceforge.net/doc/
>>>I'll have a think about the above list and draw up some conclusions this
>>>weekend.  Shall we take this to debian-doc or private email from now, r
>>>leave it here?
>>Yes.  debian-doc please.
> I still think bug fix release is good thing.
> Are you familiar with multi lingual XML document project management?  I
> am not.  I am liiking at current installation guide as the good guide.

Would you mind if I investigate creation of a new XML version, that we
can work on in parallel with the existing version?  I will also look at
how the install guide is managed.  I can start to refactor the
Reference, and you / Javi / whomever can filter in changes as and when
ready.  I would of course appreciate your input throughout, as I don't
want to go too far down the wrong road.

Reply to: