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

Bug#618257: marked as done (general: Single official manual for Debian version 6 does not exist)

Your message dated Mon, 17 Oct 2011 00:19:04 -0500
with message-id <20111017051904.GA8414@elie.hsd1.il.comcast.net>
and subject line Re: general: Single official manual for Debian version 6 does not exist
has caused the Debian Bug report #618257,
regarding general: Single official manual for Debian version 6 does not exist
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@bugs.debian.org
immediately.)


-- 
618257: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=618257
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message --- 
Package: general
Severity: wishlist


Excuse me for my bad English :-)

At this time Debian 6 has no official manual - single, full, for exact release.

It has many documentation, but current situation has next problems.

1. Information is separated onto many documents. General themes
like networking is covered by many documents. But this documents:
a) is not full;
b) often describes same questions.
Result: user must make search in many documents to find solution of some problem.
User will lost many time.

2. Documentation is often written for "Debian in general", not for exact Debian release.
Result: user can read not actual information and he/she will not know about it
some time. This time period will be lost time.

I will give a concrete example now. 

Example 1. Problem: Windows can ping other Windows by name.
Debian with default LXDE installation cannot ping Windows by name.
What should user (not very experienced in Debian) to do to enable 
"ping Windows by name" feature?

Path to solution. 
After filtering more than 20 links at http://www.debian.org/doc 
we have at least 4 documents at Debian web site that can contain answer:
http://www.debian.org/doc/manuals/debian-faq/
  no such chapter, no answer, lost time
http://www.debian.org/doc/manuals/debian-reference/
  section "5.1.2. The hostname resolution" has no answer, lost time
http://www.debian.org/doc/FAQ/
  no such chapter, no answer, lost time
http://wiki.debian.org
  
Debian wiki gives many links:

http://wiki.debian.org/DebianReference/Network
  Citate: "The new "Debian Reference (v2)" is no more build from wiki. Source will be available in DDP SVN".
  Cool, what user should do with this? No answer, lost time.

http://wiki.debian.org/NetworkConfiguration
  no such chapter, no answer, lost time.
http://wiki.debian.org/netconf
  no such chapter, no answer, lost time
http://wiki.debian.org/NetworkManager
  Debian can work without it. No answer, lost time.
http://wiki.debian.org/SAMBAClientSetup
  no such chapter, no answer, lost time

Result: no answer, lost many time. Documentation at Debian's
website has no description of "ping Windows by name" feature.
Please note that:
1) this feature is supported by Debian 6. So it is strange that it is not documented;
2) this is thing that should just work. So it must not eat many user's time.

You can say that user is stupid and he/she just should make better search (like people can do at many forums).
But I hope that you will not controvert that Debian's documentation can eat many user's time in situations where
good operating system's documentation must not eat many user's time.

You can analize many other user's problems:
- how to set up fast VNC server (what programs or X plugins available, their advantages and disadvantages,
  how to configure firewall for VNC, will VNC server work without monitor or not, how to set VNC server
  resolution if computer has no monitor etc)?
- how to define primary audio device in ALSA?
- why video playing is very slow with modern videocard and default X settings (without xorg.conf)?

I am sure that all this problems have not good solutions in current documentation on Debian's
website.

I suggest to make big and great official manual for all next Debian releases.
This manual should cover all possible aspects of using Debian - at least as operating system.
Applications and games can be documented later :-)

It may seem that this is impossible because Debian is very big. But good operating system must have
good manual! This is not impossible. The way to start creating full manual can be the following.

1. Create empty Single Debian Manual based on Wiki conception, so each useror developer will be
able to participate in it.
I know that Debian has wiki already, but now this wiki does not have task to make full
Debian manual. 

2. I hope that author of each package should write list of tasks that his/her package solves.
This list should be inserted into single Debian manual. List should contain the link to package documentation.

Steps 1 and 2 are not impossible and not even very difficult.
This steps will give us at least template for future manual. This template will be usable even without
additional processing. It will cover all Debian features because all authors will insert all features of
all packages in it. It will contain links to all documentation. All for exact defined Debian release
in single place. So, impossible will be possible :-)


Let's return to our example with VNC server. User wants to run VNC server? He/she go to single Debian manual.
Simple search by "VNC" keyword will give all VNC features of Debian and link to documentation
that contains information how to enable needed feature.

It will be good if manual will not only list of features and packages, but also will contain comparing of
solutions. In other words, manual will require some postprocessing after steps 1 and 2.

Please note that other ways to create good single manual are possible. Please write if you know this ways :-)

-----------------------------
Regards, Sergey 



-- System Information:
Debian Release: 6.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: i386 (i686)

Kernel: Linux 2.6.30-2-686 (SMP w/1 CPU core)
Locale: LANG=ru_RU.UTF-8, LC_CTYPE=ru_RU.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

--- End Message ---
--- Begin Message --- 
Hi Sergey!

sergey wrote:

> At this time Debian 6 has no official manual - single, full, for
> exact release.

This _almost_ seems like a problem that spans several packages,
suitable for consideration by the Debian developer body as a whole
(hence the "general" package).  In fact, if each document included a
summary and sufficiently rich categorization, that could be enough to
automatically generate a manual for all of Debian, just like manual
pages compiled into sections form the traditional Unix manual.

Ah, but each document _does_ already (or rather, is required by policy
to) include a summary and categorization (see the debian-policy
package for details).  If you install "dwww", you can get a nice
overview of the more established documentation this way.

Of course, that doesn't address what you were looking for.  I believe
you were looking for a single entry point that could be used as a
reference for understanding how to do things in Debian.  It would
cover the most common tasks on its own and point to other documents
for more details.  This is what the Debian Reference (package
debian-reference) is supposed to provide, so I see nothing left to do
here. :)

Thanks for your interest, and I hope these pointers can help in
contributing towards your goal.

Jonathan

--- End Message ---
Reply to: