Regarding entries Makepkg, Creating Packages, PKGBUILD

Vagabond · 2010-09-18 09:25:01

Regarding the Wiki entries Makepkg, Creating Packages, and PKGBUILD: a
task-oriented approach toward this material might be considered.

The task they address is the installation of a program that is not in
any repo, and for which the source code is accessible.

Note that the article on how to create a package is not Creating
Packages. It's Makepkg that is the overall guide, while the other two
articles provide details on how to perform the task. That
questionable organization is probably due to the fact that the entries
are not task-oriented.

It would not be necessary to put all three articles into one wiki
entry. Brief introductory remarks on each could orient the user.

That said, it is still confusing to read in Creating Packages, "Now,
you need to list the commands you used when you manually compiled the
software." What's a reader to think of this? He may ask, "When I
manually compiled WHAT software? I have not done that yet." Or he
may take "the software" to mean the code he is currently trying to
convert into a tarred and xzipped package, and think, "But I have not
done that yet, have I? Isn't that my task? What am I doing here?"
Accordingly, the ambiguities of the wording might be eliminated.
Perhaps this, or something like it, would be clearer: "Now you need to
list the commands you would use if you were manually compiling a
program from source."

Too many man pages and HOWTOs and wiki entries are instructions
written for people who do not need them. Sure, you know what the
vague and imprecise expressions and jargon mean, and the entire
process is clear to you; that means the instructions are excellent,
just as they are. But those excellent instructions may be a confusing
and misleading mess for the new arrival.

That suggests that a task-oriented approach might be best for many
information sources, especially wiki entries. A task-oriented article
breaks the big task down into chains of mini-tasks; each chain is a
list of specific actions the user must take. At each point, the
article responds helpfully to the implicit question, "What, exactly,
do you want the user to do now?"

That has not always been achieved in the current Arch wiki. For
example, in Creating Packages, the text reads, "Now you need to
implement the build() function in the PKGBUILD file." Great; the
reader is automatically thinking, "How do I implement the
build()function? You are going to tell me, right? Maybe I enter
'build()'?" The answer, as it is in the wiki entry: "This function
uses... This allows.... The first step in the build() function is to
change..." Where is the answer to the reader's natural question?

Yes, you know where and what the answer is, and you know it's so
simple that anyone who does NOT know it must be a moron. There is a
difference between idiocy and ignorance, though.

Remember this, please: spelling things out without omitting
"unimportant" or "assumed" information works as well for experts as it
works for those who appreciate all the gory details. Nobody is harmed
by complete instructions. The experts will just read them rapidly.

Perhaps the Arch wiki is not for moderately-capable Linux users; after
all, the clearly-stated premise of Arch Linux is that it is for the
"competent" Linux user. To me, that means wiki entries will be
written to levels of comprehensibility that are all over the map.
So...when folks can't understand the wiki, we'll say dismissively,
"Those people are just not ready."

I don't want to discriminate against people who, after five years of
using Ubuntu successfully, have come here to learn something about
Linux.

Nor do I approve of convoluted, sloppily-organized instructions. The
reader deserves a rational text.

Well, the above ruminations are not demands for change. Clarifying
the wiki's organization and deciphering its intent do produce a sense
of accomplishment, after all.

stefanwilkens · 2010-09-18 09:48:29

firstoff, welcome to the Arch Linux forums / community (perhaps even distro?). It is true that Arch is not for the faint of heart, but the documentation / forums / irc channels offer more than enough expertise for the willing user to solve his / her problems. Any new user is urged to read, search and investigate. You will not be spoon fed every step of the way.

This is due to the nature of the distro. Most wiki articles are written by those who do not need or seek that extra level of information that may be required for the novice user. This is not Arch's target audience and we should not be required to adjust in order to facillitate.

ideally, some information is given that should result in success (barring some sentient form of life on the user side ). If not, we have forums and irc channels where new users may come to their required answers. If said user then better understands things, he / she should update the wiki article that was found to be inadequate! This is key, and applied to bug reporting as well.

as a side observation: too much talk and too little action regarding documentation editing, imo! If users have an account and are confident: hit that edit button.

to quote someone:

Its a wiki for godsake! Create an account and start correcting.

Last edited by stefanwilkens (2010-09-18 09:51:31)

karol · 2010-09-18 13:40:04

I think you're in the perfect position to start fixing the wiki articles so that they are more task-oriented and newbie-friendly.
Just be sure to have a talk with the wiki admins before you try to do some major changes.

pointone · 2010-09-18 14:56:19

Vagabond wrote:

Sure, you know what the vague and imprecise
expressions and jargon mean, and the entire process is clear to you;
that means the instructions are excellent, just as they are.

Well said. Since we clearly do not recognize a problem, how are we to resolve it?

The wiki approach encourages collaboration. Remember that wiki contributors are not trained technical writers -- they are volunteers; possibly less experienced than you. Further, not all contributors speak (write) native English. You may find instructions written by others confusing or misleading. When attempting to perform the actions described within, you may say, "Boy, I really wish someone mentioned that and this. I had to learn on my own!" Our hope is that you then edit the page and mention this and that, so that everyone can benefit from your experience.

Arch Linux

#1 2010-09-18 09:25:01

Regarding entries Makepkg, Creating Packages, PKGBUILD

#2 2010-09-18 09:48:29

Re: Regarding entries Makepkg, Creating Packages, PKGBUILD

#3 2010-09-18 13:40:04

Re: Regarding entries Makepkg, Creating Packages, PKGBUILD

#4 2010-09-18 14:56:19

Re: Regarding entries Makepkg, Creating Packages, PKGBUILD

Board footer