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-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20110313184901.3492.22617.report...@fc3.ru
