Some packages really need documentation to be usable?

average_joe2 · 2006-08-11 16:02:21

I have installed arch64 on my laptop yesterday and I have found that I like it really much. Anyway, I realized that I will have to do some work to download all the docs I need to use my computer as I usually use it (I usually play with -dev packages, like gtk(mm) and wxwidgets, and with math programs, like maxima). I will also have to download docs on how to configure my nvidia card to use twinview, even if I actually have no plan to use it. So, because I like arch and I want to give some ideas back, why not do a poll to see how many users are satisfied by arch's current policy (basically, rm -rf /usr/share/doc) and how many would like something different? Something different would be -doc packages for packages with huge documentation (for example gtk) and integrated READMEs for package with little documentation (for example the NVIDIA driver docs). Well.. lets see what people think about that..

tomfitzyuk · 2006-08-11 20:25:00

I brought this up on the IRC but I was shot down pretty quickly, before being told to read through the mailing lists as this has already been discussed.

average_joe2 · 2006-08-11 20:57:58

I have done a quick search on the mailing-list archive and I cannot find that discussion. can you please give me the url or a good keyword to search? (i'm really curious to know how this path-based selection of docs has been justified).
Thanks for your help.

phrakture · 2006-08-11 21:18:48

average_joe2 wrote:

i'm really curious to know how this path-based selection of docs has been justified

Basically, here's the run-down that I recall:

Arch is a networked distro. You can't really be "bleeding edge" on 56k, can you? Arch assumes a stable internet connection (that is not to say it is required, but it is assumed it exists).
Basically, all the docs that one would use as a reference manual in /usr/share/doc are either info pages (which really just suck. man pages are superior) or API documentation.

API documentation is always evolving, and is easilly found online. In fact, most people would tell you it's preferrable to reference the online documentation as it will have more information than the installed docs.

gtkmm? http://www.gtkmm.org/docs/gtkmm-2.4/docs/
wxwidgets? http://wxwidgets.org/docs/

average_joe2 · 2006-08-11 21:59:19

phrakture wrote:

Arch is a networked distro. You can't really be "bleeding edge" on 56k, can you? Arch assumes a stable internet connection (that is not to say it is required, but it is assumed it exists).

There are cases where even if you have an internet connection it is much more efficent to have the documentation you are working with in your hd, instead of browsing. An example is programming, another example is using a non-trivial app, like maxima. I think this type of use just fall in the middle between a server (which is not reconfigured often) and a desktop (which use mostly trivial apps)... maybe it is called workstation?

phrakture wrote:

Basically, all the docs that one would use as a reference manual in /usr/share/doc are either info pages (which really just suck. man pages are superior) or API documentation.

This observation it package-dependent. There are programs which have a good man page, like bash. There are programs which have a good README, like the nvidia driver. There are even programs whose only documentation seem to be in the "info" format, like grub. In the end, there are also programs which have html or pdf documentation.. What can i say? I too prefer to read docs in the form of man pages. Yet i'm using programs which don't have good man pages. What do to then?

phrakture wrote:

API documentation is always evolving, and is easilly found online. In fact, most people would tell you it's preferrable to reference the online documentation as it will have more information than the installed docs.

I doubt that API documentation evolve much faster than source code. I don't understand the comparison between the quality of installed docs and online docs. If you download online docs then they become installed docs, and viceversa

Dusty · 2006-08-11 22:11:13

average_joe2 wrote:

An example is programming

This is a bad example, IMHO, since as phrakture said, you get more up-to-date API documentation online. I would never dream of using offline-documentation when I'm coding, I always keep a web-browser open to the page containing stuff I need. Well I used to when I didn't know it all by heart anyway. It must be time to learn something new.

another example is using a non-trivial app, like maxima.

or online: http://maxima.sourceforge.net/docs/manu … ima_1.html

I haven't used this one, never heard of it. When I was playing with Blender (perhaps the most non-trivial app!!), I recall downloading one tutorial, but again, I mostly read everything online. I just bookmarked it. My web browser is never closed that way.

"info" format, like grub.

or online: http://www.gnu.org/software/grub/manual/grub.html

Your point about this being package-dependent is valid, but I'd say that it will be hard to find a package in this day and age that doesn't post its docs online. And if it doesn't, I say that package is broken.

When I was on dialup, I loved the fact Arch didn't install docs for me, cause it saved on my downloading. The one document I couldn't live without back then was the Java 1.5 API... and it was a pain to get online. In that case, I did download the whole thing and store it offline, but for everything else, google gave me the docs I needed. Now that I have a super-fast always on connection, google gives me the docs I need completely painlessly. I've personally never missed offline documentation, and I appreciate my hard drive being clear.

That being said, there's nothing stopping a group of people from creating some documentation packages and either putting PKGBUILDs in AUR or creating their own repository. I just have to say it is in direct conflict with Arch's philosophy to include docs with the packaging. It was a fundamental part of Judd's initial design decision with the 0.1 release and before.

Dusty

tomk · 2006-08-11 22:13:39

I'm just a tiny bit curious about this:

average_joe2 wrote:

I will also have to download docs on how to configure my nvidia card to use twinview, even if I actually have no plan to use it.

Why do you have to download docs that you may not use?

average_joe2 wrote:

-doc packages for packages with huge documentation

Now there's your opportunity. Doc packages will never be part of Arch, but there's nothing stopping you setting up and maintaining your own "Arch-doc" repo. It would be completely contrary to this particular Arch principle, but if it scratches your itch....
I wouldn't use it, but given the regular and predictable reappearance of this topic, others might.

average_joe2 · 2006-08-11 22:36:27

Dusty claim that all docs can be easily found on the net is obviusly true, but the same argument apply almost to everythings in the opensource world. Arch provide binary packages to simplify the life of his users. Why the same cannot be done with docs?
tomk, i have to configure it becose it may happen than one day i will need it.. who know.. and it may happen even when my laptop cannot reach the internet

average_joe2 · 2006-08-11 22:58:30

tomk wrote:

Now there's your opportunity. Doc packages will never be part of Arch, but there's nothing stopping you setting up and maintaining your own "Arch-doc" repo. It would be completely contrary to this particular Arch principle, but if it scratches your itch....
I wouldn't use it, but given the regular and predictable reappearance of this topic, others might.

When I will know more about ABS and AUR I will be happy to provide -doc packages for some apps i'm using. Still i think this will not solve the problem entirely.

The Arch principle tell us that man pages are ok while READMEs are bad? Is that criterion really the best? Why not create a more flexible criterion that let package developers do a better job (without forcing them to spend times on docs, obviusly).

phrakture · 2006-08-11 23:29:42

Dusty wrote:

average_joe2 wrote:
An example is programming
This is a bad example, IMHO, since as phrakture said, you get more up-to-date API documentation online. I would never dream of using offline-documentation when I'm coding, I always keep a web-browser open to the page containing stuff I need. Well I used to when I didn't know it all by heart anyway. It must be time to learn something new.

Just to drive this point home... how many times have you been coding something and gone "man, how do I do X?", then opened a browser, searched for "doing X with libY" and got your info? It's the kind of research installed documentation wouldn't give you. Basically you make the installed docs moot because you're already looking at examples/tutorials/api docs online in some circumstances.

average_joe2 · 2006-08-11 23:39:45

phrakture wrote:

Just to drive this point home... how many times have you been coding something and gone "man, how do I do X?", then opened a browser, searched for "doing X with libY" and got your info? It's the kind of research installed documentation wouldn't give you. Basically you make the installed docs moot because you're already looking at examples/tutorials/api docs online in some circumstances.

That's really a good point.. nothin to say.. internet is surely bigger than my hd and google is usually much better than grep Yet aren't docs worth some bytes of your hd? Which criterion should be used to decide which docs include in a package?

allucid · 2006-08-11 23:47:13

The arguments have gone back and forth many times with nobody really moving on either side. Basically, the people who created/maintain Arch do not want docs so there are no docs.

That's the way it is. I don't like it but I've adapted. I used to use Info files all the time. They are hyperlinked, are integrated into my editor, and are usable offline (I am on a laptop -- not always connected). I used them mainly as a coding reference.

It's not enough to make me leave Arch, though.

tomk · 2006-08-11 23:48:45

average_joe2 wrote:

tomk, i have to configure it becose it may happen than one day i will need it.. who know.. and it may happen even when my laptop cannot reach the internet

I still don't get it :?
There are any number of things I may need at some stage in the future, and yes, it's possible that when the time comes, my laptop/ISP/telco/whatever may have a wobbly, but I'm not going to clog up my disk space "just in case".

average_joe2 wrote:

When I will know more about ABS and AUR I will be happy to provide -doc packages for some apps i'm using. Still i think this will not solve the problem entirely.

Why not? You've just described how you're going to fix it for you, and others if they're interested. The rest of us don't think it's a problem in the first place.

average_joe2 · 2006-08-12 00:02:33

tomk wrote:

There are any number of things I may need at some stage in the future, and yes, it's possible that when the time comes, my laptop/ISP/telco/whatever may have a wobbly, but I'm not going to clog up my disk space "just in case".

I have decided that i'm ready to sacrifice some kbs of my hd for that

tomk wrote:

Why not? You've just described how you're going to fix it for you, and others if they're interested. The rest of us don't think it's a problem in the first place.

If everyone who is interested do a -doc package then at the end we will have -doc packages.. ok, I agree with that.

average_joe2 · 2006-08-12 00:12:27

allucid wrote:

It's not enough to make me leave Arch, though.

As i said at the begin, i'm very satisfied with Arch and i will almost surely kept it. Also, as tomk has pointed out, AUR may let people with different ideas live happily.

I'm just trying to show that the current "arch principle" isn't very rational (when you save 100kb out of 60GB) or coherent (keep man pages, throw away READMEs, sometimes keep HTML docs sometimes throw them away?)

allucid · 2006-08-12 00:41:33

average_joe2 wrote:

allucid wrote:
It's not enough to make me leave Arch, though.
As i said at the begin, i'm very satisfied with Arch and i will almost surely kept it. Also, as tomk has pointed out, AUR may let people with different ideas live happily.
I'm just trying to show that the current "arch principle" isn't very rational (when you save 100kb out of 60GB) or coherent (keep man pages, throw away READMEs, sometimes keep HTML docs sometimes throw them away?)

I know. I think it would still be senseless even if they took up 100MB. I would rather they just let things be. If users don't want docs it's much easier to prune them out then to add them in.

tomk · 2006-08-12 08:09:51

Just to be clear - although others have suggested using the AUR, my recommendation is for you and/or others to set up an independent repo for doc packages. The reason is that, although the AUR is not an official Arch repo, the Arch packaging standards are still applied by the TUs, who look after the AUR.

stonecrest · 2006-08-12 14:46:54

allucid wrote:

That's the way it is. I don't like it but I've adapted. I used to use Info files all the time. They are hyperlinked, are integrated into my editor, and are usable offline (I am on a laptop -- not always connected). I used them mainly as a coding reference.
It's not enough to make me leave Arch, though.

I agree with everything you said. Frankly, I just think it's the stubbornness of Arch devs at this point, that they don't want to appear like they made a silly or irrational choice. It's pretty absurd to assume that just because most Arch users have a high-speed connection for staying up-to-date with packages, that they're on said connection all the time. Many laptop users fall in this boat.

But whatever, it's been hashed, rehashed, and nothing is going to change (heck, it's the same X people that argue against it everytime). Hooray for a 5 year old decision that would cause no harm and many people don't like. I love Arch to death, but this is the only thing that really peeves me about it.

mpie · 2006-08-12 15:34:22

you could always add keep docs to makepkg.conf and recompile your system if it bothers you this much.....
see man makepkg

allucid · 2006-08-12 15:46:41

It doesn't bother me enough to recompile or start a new repo. Like I said, it's just an annoyance and I've adapted. If it were enough to make me recompile everything I would just go with Gentoo instead of trying to retrofit Arch. Last time I checked, there aren't any perfect Linux distros out there.

average_joe2 · 2006-08-12 18:15:03

stonecrest wrote:

I agree with everything you said. Frankly, I just think it's the stubbornness of Arch devs at this point, that they don't want to appear like they made a silly or irrational choice.users fall in this boat.

Even if they think they have made the right choice (and in fact i think it is the right choice for some types of users) they could do somethings to clarify that choiche (they should define how to determine if a docs is worth to stay in a package)

average_joe2 · 2006-08-12 18:22:33

average_joe2 wrote:

Even if they think they have made the right choice (and in fact i think it is the right choice for some types of users) they could do somethings to clarify that choiche (they should define how to determine if a docs is worth to stay in a package)

I say that becose the fact that mostly annoy me is just the lack of a decent criterion. For example, XFCE has some docs installed and i seriusly doubt i will never read them. Another example is as i already said the nvidia driver, which provide two man pages of rarely used tools and lack the README that tell us how to configure X.

ralvez · 2006-08-12 20:47:50

I think that this whole thing boils down to a very simple thing: working style.
When I'm working on a system and need some info I always go to the web for the following reasons:
1. I'll get several different answers to the same problem, wich may widen the scope of my understanding (well I'm not that bright ... what can I do ) to unforeseen scenarios.
2. Get the latest info along with some history (from older postings) of a specific problem.
3. I learn more when I research a problem than when I just get a "do this" from say a read me or even man pages.
4. When it comes to programming I always learn more from what other people have done (be it good or bad) than from any other source.

This is not to say that average_joe2 has no valid points in this posting, especially if we look at the "problem" from his angle, I just think that his working style is different ... and this thread can go forever without everyone fully agreeing on all points.

average_joe2 · 2006-08-13 14:31:23

ralvez wrote:

1. I'll get several different answers to the same problem, wich may widen the scope of my understanding (well I'm not that bright ... what can I do ) to unforeseen scenarios.
2. Get the latest info along with some history (from older postings) of a specific problem.
3. I learn more when I research a problem than when I just get a "do this" from say a read me or even man pages.
4. When it comes to programming I always learn more from what other people have done (be it good or bad) than from any other source.

This is all true and reasonable but it doesn't work as a counter to my previous two post
Thanks for posting here and sharing ideas anyway.. (i think it would be usefull to do a poll to see the percentage of people that would like to do some changes).

Dusty · 2006-08-13 16:40:07

Feel free to post a poll, we won't delete it right away if its politely worded. But remember that this forum is a pretty skewed sampling of the Arch Linux user population and not the best way to get fair results. Also remember that the devs do things their way because they want them that way.

I've yet to see Judd unwilling to change something just because it was his decision earlier; requirements change. You should see some of the flareups that go on when they do change things (search for module autoloading, or devfs vs udev for examples)! Regardless of what results the poll shows, I highly doubt you'll get any changes from it. I'd also suggest from experience in this community that the poll results will be around :

10% yes
10% no
80% Who cares

(and that's bearing in mind that most of the who cares population aren't bothering to vote).

Generally for such conflicts there is a solution that can almost satisfy everyone. A separate repository for documentation would certainly do this, I can even surmise that if such a repository was set up, people would quickly write scripts to sync it so that any package that was installed would automatically have the associated documentation installed as well.

The main point is, as usual, if you have a problem nobody else cares about, you can't demand others fix it for you.

Dusty

Arch Linux

#1 2006-08-11 16:02:21

Some packages really need documentation to be usable?

#2 2006-08-11 20:25:00

Re: Some packages really need documentation to be usable?

#3 2006-08-11 20:57:58

Re: Some packages really need documentation to be usable?

#4 2006-08-11 21:18:48

Re: Some packages really need documentation to be usable?

#5 2006-08-11 21:59:19

Re: Some packages really need documentation to be usable?

#6 2006-08-11 22:11:13

Re: Some packages really need documentation to be usable?

#7 2006-08-11 22:13:39

Re: Some packages really need documentation to be usable?

#8 2006-08-11 22:36:27

Re: Some packages really need documentation to be usable?

#9 2006-08-11 22:58:30

Re: Some packages really need documentation to be usable?

#10 2006-08-11 23:29:42

Re: Some packages really need documentation to be usable?

#11 2006-08-11 23:39:45

Re: Some packages really need documentation to be usable?

#12 2006-08-11 23:47:13

Re: Some packages really need documentation to be usable?

#13 2006-08-11 23:48:45

Re: Some packages really need documentation to be usable?

#14 2006-08-12 00:02:33

Re: Some packages really need documentation to be usable?

#15 2006-08-12 00:12:27

Re: Some packages really need documentation to be usable?

#16 2006-08-12 00:41:33

Re: Some packages really need documentation to be usable?

#17 2006-08-12 08:09:51

Re: Some packages really need documentation to be usable?

#18 2006-08-12 14:46:54

Re: Some packages really need documentation to be usable?

#19 2006-08-12 15:34:22

Re: Some packages really need documentation to be usable?

#20 2006-08-12 15:46:41

Re: Some packages really need documentation to be usable?

#21 2006-08-12 18:15:03

Re: Some packages really need documentation to be usable?

#22 2006-08-12 18:22:33

Re: Some packages really need documentation to be usable?

#23 2006-08-12 20:47:50

Re: Some packages really need documentation to be usable?

#24 2006-08-13 14:31:23

Re: Some packages really need documentation to be usable?

#25 2006-08-13 16:40:07

Re: Some packages really need documentation to be usable?

Board footer