FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Debian > Debian Development

 
 
LinkBack Thread Tools
 
Old 03-13-2011, 05:49 PM
sergey
 
Default Bug#618257: general: Single official manual for Debian version 6 does not exist

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



--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 20110313184901.3492.22617.reportbug@fc3.ru">http://lists.debian.org/20110313184901.3492.22617.reportbug@fc3.ru
 

Thread Tools




All times are GMT. The time now is 07:06 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org