[uClinux-dev] A pervasive problem...

gerg gerg at snapgear.com
Sat Nov 17 09:00:38 EST 2001

Hi Dave,

Dave_Pfaltzgraff at patapsco.com wrote:
> This message is only food for thought. If the result is a flame war, then it
> means I have touched on some sensitive areas and so be it. You must remember
> that my position is not as a developer but as a user and occasional contributor.
> In a series of messages titled "Adding new board support [& other questions]",
> Bruce Patterson attempted to find direction in performing a specific task.
> Rather than a simple response that may have given him the direction he needed,
> he was chided and told to "read the source." I thoroughly understand his
> frustration as I have been there several times. The heritage of the *nix
> community is rich and steeped in history. Much of what is done is not intuitive.
> My most recent adventures resulted in a contribution to http://home.at/uldp in
> the form of sections 5 (Adding Device Drivers) and 6 (Adding Applications). This
> contribution was made only after I submitted it to this group and did not
> receive any corrections.
> Now, I find that John Jeffers is on a similar quest. I am very pleased that he
> found my contribution. However, I find that the basic structure of the make
> system has changed making my contribution (5) obsolete. I guess the mistake I
> made was in not fully identifying the distribution (20010529) that I based my
> studies on. However, I see that his distribution (20010622) is only a month
> newer. All this can be learned after a post to this group brings the message "
> Frankly, this has changed :-)"

Well, that is a little unfair. You are taking that quote out of context.

> >from my viewpoint, I can only ask questions:
>   1. Why was such a radical (apparently) change made in such a short time?

I disagree. I guess it depends on your perspective. I see the changes
as evolutionary.

>   2. Why was there no documentation to support this?

There has never been any before. This is no different this time.
I guess if you where paying money you would have reason to complain.

>   3. Why didn't anyone correct me when I submitted my document to this list a
> mere month ago?

Maybe because it was right when referring to the correct source package?

>   4. Etc...


> I'm not asking these questions to say that the changes are wrong or that anyone
> is in the wrong for doing what they did. In fact the first question arises
> because the evolution of software methodologies is a personal interest. The key
> issue here can be summarized in the following issues which I consider to be
> important points:
>   1. The Linux community claims that they want "Linux everywhere"

Generalizations are always dangerous. Who _exactly_ is the Linux
The vocal minority?

>   2. There are many of us who like Linux for a myriad of reasons
>   3. Most of us are new to the *nix environment

Really?  Do you think so?

uClinux is sort of interresting in this respect. It is for embedded
systems. Generally I find the calibre of developer in this spehere a
lot more sophisticated than the desktop weenies. Many I communicate
with have some UNIX backgound.

>   4. Without any introductory documentation, it's only natural that we have
> seemingly simple questions.

Even if you have documentation you will get simple questions. No amount
of written words will totally stop this. Hopefully you get less.

>   5. To be rebuffed and told to "read the source" without direction as to where
> the introduction (much less chapter 1) can be found, only alienates us.

I suggest everyone read Eric Raymond's piece on how to ask intelligent
questions. It is quite good:


> If this attitude perpetuates, we will fall back on other O/Ss that do provide
> reasonable documentation and then where will Linux be?

I guess this is a case of perspective too. When I am working on a peice
source code (no matter free or proprietary) I dig into it until I find
I am looking for. I rarely find documentation that usefull, even when I
have paid good $ for it.

> If we are to grow as a community, we must take the time to document what we do.
> This is not meant to imply that we need full module by module flowcharts, etc.
> Look at how useful Rubini's book is without that level of detail. His book
> provides the fundamentals that give the reader direction in his pursuit of
> understanding. Without some very basic documentation, we will find, as Bruce
> did, that history repeats itself in that any newbie must repeat what all the
> others before him have done. Namely, stumble through seemingly arcane code until
> the pieces start to fall together. (Anyone who does not consider 'make' arcane
> must be intimately familiar with it!) How many potential members have we lost
> because they were never able to find this connection?
> In the case of uClinux, if someone were able to put a text together that
> provided a fundamental understanding, not of the kernel but of the directory
> structure and the build process, I would purchase it. Yes, even if an on-line
> copy was available! Properly done, this would be an excellent resource to give
> me initial direction and to serve as a refresher as time goes on. Sure, anything
> in development is, by definition, in a state of flux, but, as somone on this
> list pointed out, old documentation is btter than no documentation. Linux
> (kernel and all that) is a great thing, but my key interest is in the
> applications and it is the applications that will give life to Linux and ensure
> its success "everywhere".
> Another way to look at this, after reviewing the uldp site, is to ask: How many
> of the FAQs would be answered by having a basic overall text to give direction?
> Alternately: How much traffic on this list would be eliminated by enabling the
> newbies to ask more specific questions?

I doubt anyone disagrees. So the question is are you prepared to do
something about it?  Are you going to take the time to write some
doco and keep it up to date. If not you, who else?


Greg Ungerer  --  Chief Software Wizard        EMAIL:  gerg at snapgear.com
Snapgear                                       PHONE:    +61 7 3279 1822
825 Stanley St,                                  FAX:    +61 7 3279 1820
Woolloogabba, QLD, 4102, Australia               WEB:   www.snapgear.com
This message resent by the uclinux-dev at uclinux.org list server http://www.uClinux.org/

More information about the uClinux-dev mailing list