Newbies, Development, Documentation and Guides - An invitation to discuss

GoogleGroups
1

This topic is not limited to Beagleboard specifically, but I thought it would be interesting to solicit a discussion here as Beagleboard seems to be one of the primary boards that introduces people to Open Source Embedded Development. (and it’s my embedded development board of choice).

I’ve spent a lot of the last few months getting up to speed on embedded development and all that entails (and there’s a lot to learn - with the tools, linux config, applications and variations in the hardware versions). Reading the various IRC, blogs, groups and websites, there is a wealth of information, but as has been noted many times, much of it is out of date and is not relevant in all cases.

I’ve read many posts from newbies and early developers exclaiming frustration at what is perceived as lack of documentation and an absense of a big picture which can help put problems in context. My own experience felt a bit like Alice falling down the rabbit hole, investigating some problems just took me deeper and deeper, and I had to learn stuff to a level far beyond my initial expectation. OpenEmbedded certainly makes the whole process much easier, but it certainly doesn’t appear to be the case that you can just pick the packages, press build and get a fully working image every time (and I don’t think that should be the expectation).

At the other end of the spectrum, I personally, would like to thank the gurus/experts who review the updates and provide guidance (note I avoid the word “support” very deliberately) to help us onto the first rung of the ladder. These experts must be dedicating a huge portion of their time, and I for one am grateful for that. I read an interesting e-discussion recently where someone was airing frustration about the lack of documentation, and how they could not base a commercial development on this state of affairs. The summary of the responses was basically that Open Source is free and you get what you pay for. It is unsupported, and the developers have better things to do with their time than write documentation. Users are expected to roll their sleeves up and read the source code. But there’s a considerable (huge) learning curve for most to get to the point of being able to do this.

I can see both sides of the argument, as someone who has struggled to get things working and having trundled down a lot of blind alleys, the lack of documentation and context of some blogs has made me frustrated at times. However, I don’t think that anyone in the community owes me anything. It’s all free, after all.

So here’s the question. Is there a middle ground, tool, process or something which can be community driven and low impact (certainly not as cumbersome as documentation), but which helps provide relevant guidance? I’m guessing that a lot of the same questions are raised time after time, and the guru’s must get a bit bored of answering them (I can almost see the eyes rolling up into the forehead sometimes and their patience is admirable ;-)). Many questions posted also remain unanswered, possibly also because they have been asked so many times before.

The advantage of having some better, more reliable guidance is that it should reduce the number of simple questions, and might reduce the number of talented folks that drop out completely due to frustration. The more people that stay productive in the game, the more progress is made by all. One disadvantage is that making it easier to find solutions may discourage some from looking deeper into the code and thus may perpetuate the “it should just work out of the box” myth.

So here’s some things that I feel would have helped me in my quest:

  1. Many blogs were out of date and related to different versions of Angstrom Dist/Linux kernel/OE version/hardware. Some way to bring the related blogs together and relate them to the various versions of tools etc would help guide folks to a solution that would be more likely to work for them. Often the versions are not recorded in the blog. In my case I was trying to get a wifi dongle to work and I went down numerous blind alleys - but learnt a lot on the way. It would be interesting to ask users of the blog to indicate as to whether or not the procedure worked for them (and record the versions used). In that way a user could see if the method was considered reliable or not for their environment (and if not, whether there are common problems). I guess this would help provide similar statistics as an overnight build regression test.

  2. When things didn’t work, what I often wanted to do, was recreate the same environment as the blogger had used, to be able to start from a known stable base. Something that addresses the above might help acheive that.

  3. If the above could be done across a number of common tasks, then perhaps a step by step training course would fall out that goes beyond “Hello World” to familiarise beginners with the myriad of tools that they will need in the development arsenal (OE, Git, Linux Configure). I for one, believe I have found problems and have been unsure about the proper way to submit bug reports / solutions.

What other light touch things would have helped people over the early hurdles to get them to the point where they could contribute. Full documentation is obviously not an option, but is there something community driven that could make the mass of data that is already out there more relevant and more organised, and at the same time add extra validation? Or (and I fear this may be the case), are the number of variables so large that the task rapidly becomes unmanageable?

Regards
Zigs

2

I've read many posts from newbies and early developers exclaiming
frustration at what is perceived as lack of documentation and an absense of
a big picture which can help put problems in context. My own experience
felt a bit like Alice falling down the rabbit hole, investigating some
problems just took me deeper and deeper, and I had to learn stuff to a
level far beyond my initial expectation.

There's simply so much that can be done with something as complex as a
Beagle, it's hard to document all of them.

OpenEmbedded certainly makes the
whole process much easier, but it certainly doesn't appear to be the case
that you can just pick the packages, press build and get a fully working
image every time (and I don't think that should be the expectation).

Heh. My opinion is that the words "OpenEmbedded" and "easier" shouldn't
be used in the same sentence. But to each their own.

I read an interesting e-discussion recently
where someone was airing frustration about the lack of documentation, and
how they could not base a commercial development on this state of affairs.

You'd be surprised at how much "commercial development" is based off
situations like this. It's way more common than you seem to think.

It compiles? Ship it!
That's not always said in a joking way. That's often how commercial
development gets done.

The summary of the responses was basically that Open Source is free and you
get what you pay for. It is unsupported, and the developers have better
things to do with their time than write documentation. Users are expected
to roll their sleeves up and read the source code. But there's a
considerable (huge) learning curve for most to get to the point of being
able to do this.

Yes. But most of the people who know enough to write good
documentation have more interesting things to work on than writing
documentation for new people. If there was money involved, I bet that
would change, but not many companies see benefit from paying for better
newbie documentation right now.

Heck, TI didn't see value in mainlining their kernel code till
recently. Granted, that's changed and these days TI is a rather good
contributor. So, maybe the documentation thing will change, too.

I can see both sides of the argument, as someone who has struggled to get
things working and having trundled down a lot of blind alleys, the lack of
documentation and context of some blogs has made me frustrated at times.
However, I don't think that anyone in the community owes me anything. It's
all free, after all.

What if there was a paid training system?
Would you pay? How much and for what?
I'm sure there's people in the community who would be happy to take
your money in exchange for creating better documentation. But most
people aren't willing to pay what it costs to do so.

So here's the question. Is there a middle ground, tool, process or
something which can be community driven and low impact (certainly not as
cumbersome as documentation), but which helps provide relevant guidance?

elinux.org?
This mailing list?

The advantage of having some better, more reliable guidance is that it
should reduce the number of simple questions, and might reduce the number
of talented folks that drop out completely due to frustration.

I don't think that many people drop out due to frustration with newbie
questions. They may stop responding to those questions, but I don't
think they stop being a part of the community. At least not most of
the time.

So here's some things that I feel would have helped me in my quest:

1) Many blogs were out of date and related to different versions of
Angstrom Dist/Linux kernel/OE version/hardware. Some way to bring the
related blogs together and relate them to the various versions of tools etc
would help guide folks to a solution that would be more likely to work for
them.

It's very very hard to keep up. There's so many pieces that go into
something like a software distribution for a Beagle, unless you're
dedicated to keeping up with all those pieces and each of their
development cycles, it's almost a lost cause.

That's mostly what drove distributions (like Ubuntu or RedHat) to
release in cycles, every 6 or 12 or 18 months. You have less to keep
up with, just follow your favored distribution.

2) When things didn't work, what I often wanted to do, was recreate the
same environment as the blogger had used, to be able to start from a known
stable base. Something that addresses the above might help acheive that.

Like a standard for creating virtual machine images that people would
link to and say, "I used that image to do this action?" And the image
would have all the same versions of software that the blogger used?

That's a good idea.

How would you implement it? What would be the requirements?

3) If the above could be done across a number of common tasks, then perhaps
a step by step training course would fall out that goes beyond "Hello
World" to familiarise beginners with the myriad of tools that they will
need in the development arsenal (OE, Git, Linux Configure). I for one,
believe I have found problems and have been unsure about the proper way to
submit bug reports / solutions.

elinux.org already covers a lot of this. When you (or anyone else)
see that elinux.org is incorrect or missing something, add it.

What other light touch things would have helped people over the early
hurdles to get them to the point where they could contribute. Full
documentation is obviously not an option, but is there something community
driven that could make the mass of data that is already out there more
relevant and more organised, and at the same time add extra validation? Or
(and I fear this may be the case), are the number of variables so large
that the task rapidly becomes unmanageable?

Full documentation is an option, if there's people willing to pay for
it. Anything less than money will provoke a best-effort by the
community approach, which is what we have today (except for those
employed to work on Beagles, but that's a very small team).

The number of variables is very large. But, with pay, I think a small
team could document many of them. Without more money, it's hard to get
much better than what exists today. It's actually very very good in
comparison to what was available even a few years ago.

If you venture outside of Beagle-land, you'll find a much worse state
of affairs in regards to documentation. The Beagle community is pretty
good compared to, for example, Freescale iMX53 QSB things.

-Andrew

3

snip..
If you venture outside of Beagle-land, you'll find a much worse state of affairs in regards to documentation. The Beagle community is pretty good compared to, for example, Freescale iMX53 QSB things.

I tried for about an hour yesterday attempting to find somewhere which stated in a clear and concise manner how many SPI busses and chip selects were brought out on the QSB expansion header. So I can second this example, it was exasperating...

4

According to the QSB-R hardware user guide [1], there's 2 SPI interfaces
on the expansion header. They default to 1.8V levels, I think, but
supposedly you can change them to 3.3V levels by modifying the PMIC
registers. I'm not sure if the non "-R" board, with the Dialog brand
PMIC can do the same.

[1]:http://cache.freescale.com/files/32bit/doc/ref_manual/IMX53RQSBRM-R.pdf

Regardless, the mating connector for the QSB expansion header is like
$10 in small quantities. That's a bit pricy.

See section 6 of the QSB-R hardware user guide for the mux info. I
believe the 1 CSPI has 4 chip selects and the 1 ECSPI has 3 chip
selects. ECSPI has bigger fifos and a few more capabilities than CSPI,
within the silicon.

I considered the iMX53 for the project I'm working on now. Decided
against it in favor of the Bone and AM33xx. If that means anything.

-Andrew

PS: See, you should have just asked the Beagle mailing list about your
QSB question :slight_smile:

5

Hi Andrew,

Many thanks for your detailed and considered response, and I agree that money can incentivise a number of people, but I was hoping to explore what might be possible within the community. There are a number of very clever people who collaborate on developing a wonderful system made of parts (Linux, Angstrom, Hardware etc). There is a focus and a lot of control that goes into admitting changes into all of these (using version control, patches, regression testing etc). However the community does not appear to have the same control over information on methods (favouring the “read the code” mantra) and it probably could. Could we treat blogged methods for acheiving things on Beagle the same as code in that the method gets submitted, reviewed and released. (Once submitted it could be available as untested, until someone confirms it works - along with the various versions of the pieces that bring it together. I’m not sure how it would be best acheived and would want it to (initially at least) be a series of validated links to existing blogs to make it more of an evolving database perhaps. It would need to be simple to get folks to want to use it.

I may have misled you on the commercial aspect. I was only paraphrasing a chat that I read recently and a sentiment I have seen more than once. I really started this discussion to explore if there might be a low effort way to provide more guidance and lower the frustration without having to write pages and pages of docs in a way to help promote the community. The “dropouts” that I had in mind are newbies (either with a commercial idea, or community spirit) who hit the very steep early steps and potentially give it up. I hadn’t meant to imply that the folks offering advice would dropout.

Wrong advice can sometimes be worse than no advice, because you can spend ages trying to get something working that someone on a blog describes and says “…taa-dah, and then it all just worked.”, but for you it doesn’t, and you don’t know why.
I just get a feeling of there being a lot of folks at the two opposite ends of the spectrum. Newbies who have unreasonable expectations of how easy it is all going to be and are anticipating commercial grade software at the push of a button, and at the other end, the folks who have clearly invested years learning all of this stuff, and for whom, a lot of it is now second nature. The land between the two groups appears to me to be a bit of a maze of misdirection and beartraps, and while I know I’m not going to get a satnav to get me there, I would settle for a sketched map on the back of beermat (with something to let me know if the maze has been changed since the sketch was drawn).

I should declare that I’m a hardware engineer of some 28 years experience and I’m investing this time to gain more understanding about how the BSP and driver writers do their thing so I can have more sympathy with thier monumental challenges.

So the thought behind this discussion was to solicit other thoughts on what might be done as a community and what would make it easy to adaopt/use to gain reasonable participation. I also hoped that someone might suggest existing tools that could be adapted. Would it be based on a database, forum, Wiki, simple set of web links.

I agree that there are a large number of applications so the system would need to be extensible by the user and catagorised (Networking, Video, Audio, Robotics, Interfaces…). Most of all though, the methods would need to be rooted to a point in time and against various versions, so it’s clear what is out of date. A classic early source of confusion is the U-boot differences between Beagleboard and Beagleboard_XM with the loss of the NAND. If you get the wrong method for the wrong board, you end up in a world of pain until you discover that the method is not relevant for your hardware.

I could also envisage that the proposed system might pursuade users to register and as part of that they could enter the configuration of hardware that they have (Beagleboard/ XM/ Beaglebone). This might help steer users towards the relevant answers, but could also be used to help record the validated tests.

What I’m not trying to do is short cut the learning process. It’s clear that to acheive anything with Beagle you have to get your nose into the books/webpages. But I feel a little thought might help folks avoid some of the many dead ends.

Many thanks for the elinux.org recommendation. I’ve passed through it and it is logged in my favorites along with all the blogs I’ve bookmarked (relevant and not relevant). It’s helpful to get a recomendation to spend more time there. I’m just finishing an excellent Embedded Linux Primer book, which has removed a few of the veils. elinux.org will be my next stop.

Once again, many thanks for the response.

Zigs

6

This topic is not limited to Beagleboard specifically, but I thought it
would be interesting to solicit a discussion here as Beagleboard seems to be
one of the primary boards that introduces people to Open Source Embedded
Development. (and it's my embedded development board of choice).

I've spent a lot of the last few months getting up to speed on embedded
development and all that entails (and there's a lot to learn - with the
tools, linux config, applications and variations in the hardware versions).
Reading the various IRC, blogs, groups and websites, there is a wealth of
information, but as has been noted many times, much of it is out of date and
is not relevant in all cases.

I've read many posts from newbies and early developers exclaiming
frustration at what is perceived as lack of documentation and an absense of
a big picture which can help put problems in context. My own experience felt
a bit like Alice falling down the rabbit hole, investigating some problems
just took me deeper and deeper, and I had to learn stuff to a level far
beyond my initial expectation. OpenEmbedded certainly makes the whole
process much easier, but it certainly doesn't appear to be the case that you
can just pick the packages, press build and get a fully working image every
time (and I don't think that should be the expectation).

At the other end of the spectrum, I personally, would like to thank the
gurus/experts who review the updates and provide guidance (note I avoid the
word "support" very deliberately) to help us onto the first rung of the
ladder. These experts must be dedicating a huge portion of their time, and I
for one am grateful for that. I read an interesting e-discussion recently
where someone was airing frustration about the lack of documentation, and
how they could not base a commercial development on this state of affairs.
The summary of the responses was basically that Open Source is free and you
get what you pay for. It is unsupported, and the developers have better
things to do with their time than write documentation. Users are expected to
roll their sleeves up and read the source code. But there's a considerable
(huge) learning curve for most to get to the point of being able to do this.

I can see both sides of the argument, as someone who has struggled to get
things working and having trundled down a lot of blind alleys, the lack of
documentation and context of some blogs has made me frustrated at times.
However, I don't think that anyone in the community owes me anything. It's
all free, after all.

So here's the question. Is there a middle ground, tool, process or something
which can be community driven and low impact (certainly not as cumbersome as
documentation), but which helps provide relevant guidance? I'm guessing that
a lot of the same questions are raised time after time, and the guru's must
get a bit bored of answering them (I can almost see the eyes rolling up into
the forehead sometimes and their patience is admirable ;-)). Many questions
posted also remain unanswered, possibly also because they have been asked so
many times before.

The advantage of having some better, more reliable guidance is that it
should reduce the number of simple questions, and might reduce the number of
talented folks that drop out completely due to frustration. The more people
that stay productive in the game, the more progress is made by all. One
disadvantage is that making it easier to find solutions may discourage some
from looking deeper into the code and thus may perpetuate the "it should
just work out of the box" myth.

So here's some things that I feel would have helped me in my quest:

1) Many blogs were out of date and related to different versions of Angstrom
Dist/Linux kernel/OE version/hardware. Some way to bring the related blogs
together and relate them to the various versions of tools etc would help
guide folks to a solution that would be more likely to work for them. Often
the versions are not recorded in the blog. In my case I was trying to get a
wifi dongle to work and I went down numerous blind alleys - but learnt a lot
on the way. It would be interesting to ask users of the blog to indicate as
to whether or not the procedure worked for them (and record the versions
used). In that way a user could see if the method was considered reliable or
not for their environment (and if not, whether there are common problems). I
guess this would help provide similar statistics as an overnight build
regression test.

It's interesting that you say this. I've been tinkering with an idea
to implement on the elinux.org wiki that would solve this problem.
Essentially, the solution would be a page on teh wiki where one could
select their board and software versions, hit return and the wiki
returns a list of all pages relevant to those selections. You can
sort of already do this by clicking on a categories page for your
relevant board, but the result is not as granular as it should be.

2) When things didn't work, what I often wanted to do, was recreate the same
environment as the blogger had used, to be able to start from a known stable
base. Something that addresses the above might help acheive that.

This is not unlike what Koen provides with the Angstrom image builder,
is it not? I mean, you'll never be able to ensure you've got an
identical environment to some random blogger, but it's better than
nothing.

3) If the above could be done across a number of common tasks, then perhaps
a step by step training course would fall out that goes beyond "Hello World"
to familiarise beginners with the myriad of tools that they will need in the
development arsenal (OE, Git, Linux Configure). I for one, believe I have
found problems and have been unsure about the proper way to submit bug
reports / solutions.

What other light touch things would have helped people over the early
hurdles to get them to the point where they could contribute. Full
documentation is obviously not an option, but is there something community
driven that could make the mass of data that is already out there more
relevant and more organised, and at the same time add extra validation? Or
(and I fear this may be the case), are the number of variables so large that
the task rapidly becomes unmanageable?

Anyway, I'm working on trying to solve this style of problem, stay tuned.

7

Hi Wmat,

Firstly, I want to thank Andrew for sending me back to your excellent elinux.org site. I had visited before, but had set off on the usual trail through other websites and had not made it back to elinux.org for a while. I think you do an excellent job on the pages, and it’s great news that you’ve been looking at a similar idea to that which I’ve proposed.

I had a short look around and I drilled down into some areas that are of interest to me (Beagleboard → Graphics Accelerator). The sites that I visited were a bit outdated, and I am guessing are Beagleboard specific and I’d like to cover Beagleboard_XM. A few ideas came to mind,I don’t know how feasible/desitable they would be, but I’d welcome your thoughts.

  1. A simple one would be to have a page below the subject (Beagleboard → Graphics Accelerator) which simply had three choices (Beagleboard, Beagleboard_XM). The current “Beagleboard only” links would then be kept under the relavant link, whereas new links could be forged for XM and perhaps even Beaglebone info. (This only caters for hardware variations, not the myriad of software variations)

  2. Would it be possible to have some sort of voting system against the links which would allow folks to click to say whether or not a link helped for their particular environment hardware combination. The combinations would need to be limited, but it would help a bit. Maybe hardware could be a starting point (so three options), perhaps add linux kernel version. Even better, if there could be a widget that could be added to peoples blog webpages similar to the “like thumbs up” button which then takes folks to a page that allows them to enter their hardware/software configuration (their default config could be stored as a cookie perhaps) and then whether or not that web page had solved their problem. Could this data be collated and displayed on elinux.org next to each link in some way, or even be used to do what you are proposing and allow folks to request only links voted to be relevant to their environment (or at least have those links highlighted). As you might guess, I’m very keen on the idea of somehow harnessing the power of the crowd for providing guidance on solving the problems.

Regarding Koen’s Narcissus, as fantastic as it is, I’m not sure how it solves my problem. My current modus operandi is when I hit a problem, I google to find the generous blogs of folks doing something similar, I try the same prcodure with my environment. If that fails I try to recreate the same or a similar environment to the blogger. If that works, I the increment the variables to find the failing element. Perhaps if I illustrate with an example. The first thing I tried to do was get a Wifi dongle working with Beagleboard_XM. I found a number of excellent blogs which described various processes of getting dongles up and running. There was a steep learning curve for me where I had to learn about compiling drivers and making sure firmware was in the right place etc. Some of the blogs were detailed to some degree but again I guessed that they related to Beagleboard and not XM. In the end my problem was solved by installing various additional kernel modules, and was complicated by the fact the OpenEmbedded-core appeared to be ignoring my kernel config changes (a known bug), but it was a circuitous route to get to a working environment. Whilst I have learnt a lot, and that is valuable, I have to admit to losing several full days chasing red herrings on more than one occasions, and it’s those wild goose chases that I’m wondering if we can erradicate or minimise. So what I would like to be able to do is replicate the envoronment used on the blog. If the blogger doesn’t detail the environment, then the voting system over time will highlight what works and what doesn’t, so allowing me a fighting chance of recreating a working system (ir ruling this blog out as not relevant). Being fair, many of the blogs were written before Beagleboard_XM existed, so there was no reason at that time to note the board type, But the voting system may take care of that (again, over time).

Thoughts?

Zigs

8

Hi Ziggy,

You’ve raised what I think is an important issue to the future of Beagleboard/Beaglebone (documentation), and made some well-reasoned suggestions.

I wonder how many people who’ve used the eLinux.org site realize it’s a wiki, and they can therefore edit the contents? You have to login in order to see the “edit” link, so my guess is that a lot of people never thought about updating the pages themselves.

I don’t know how to convert readers to contributors: I guess it’s a common problem for all types of wikis. Maybe it would help if the site prominently encouraged reader input. I will say that I’m amazed at how helpful people are on this Google Group. It’s rare that a question gets asked without some kind of response. The willingness to help others definitely exists. It would be great to see that spirit channeled into a wiki of some sort.

Dan.

9

Hi Wmat,

Firstly, I want to thank Andrew for sending me back to your excellent
elinux.org site. I had visited before, but had set off on the usual trail
through other websites and had not made it back to elinux.org for a while. I
think you do an excellent job on the pages, and it's great news that you've
been looking at a similar idea to that which I've proposed.

I had a short look around and I drilled down into some areas that are of
interest to me (Beagleboard -> Graphics Accelerator). The sites that I
visited were a bit outdated, and I am guessing are Beagleboard specific and
I'd like to cover Beagleboard_XM. A few ideas came to mind,I don't know how
feasible/desitable they would be, but I'd welcome your thoughts.

1) A simple one would be to have a page below the subject (Beagleboard ->
Graphics Accelerator) which simply had three choices (Beagleboard,
Beagleboard_XM). The current "Beagleboard only" links would then be kept
under the relavant link, whereas new links could be forged for XM and
perhaps even Beaglebone info. (This only caters for hardware variations, not
the myriad of software variations)

2) Would it be possible to have some sort of voting system against the links
which would allow folks to click to say whether or not a link helped for
their particular environment hardware combination. The combinations would
need to be limited, but it would help a bit. Maybe hardware could be a
starting point (so three options), perhaps add linux kernel version. Even
better, if there could be a widget that could be added to peoples blog
webpages similar to the "like thumbs up" button which then takes folks to a
page that allows them to enter their hardware/software configuration (their
default config could be stored as a cookie perhaps) and then whether or not
that web page had solved their problem. Could this data be collated and
displayed on elinux.org next to each link in some way, or even be used to do
what you are proposing and allow folks to request only links voted to be
relevant to their environment (or at least have those links highlighted). As
you might guess, I'm very keen on the idea of somehow harnessing the power
of the crowd for providing guidance on solving the problems.

Regarding Koen's Narcissus, as fantastic as it is, I'm not sure how it
solves my problem. My current modus operandi is when I hit a problem, I
google to find the generous blogs of folks doing something similar, I try
the same prcodure with my environment. If that fails I try to recreate the
same or a similar environment to the blogger. If that works, I the increment
the variables to find the failing element. Perhaps if I illustrate with an
example. The first thing I tried to do was get a Wifi dongle working with
Beagleboard_XM. I found a number of excellent blogs which described various
processes of getting dongles up and running. There was a steep learning
curve for me where I had to learn about compiling drivers and making sure
firmware was in the right place etc. Some of the blogs were detailed to some
degree but again I guessed that they related to Beagleboard and not XM. In
the end my problem was solved by installing various additional kernel
modules, and was complicated by the fact the OpenEmbedded-core appeared to
be ignoring my kernel config changes (a known bug), but it was a circuitous
route to get to a working environment. Whilst I have learnt a lot, and that
is valuable, I have to admit to losing several full days chasing red
herrings on more than one occasions, and it's those wild goose chases that
I'm wondering if we can erradicate or minimise. So what I would like to be
able to do is replicate the envoronment used on the blog. If the blogger
doesn't detail the environment, then the voting system over time will
highlight what works and what doesn't, so allowing me a fighting chance of
recreating a working system (ir ruling this blog out as not relevant). Being
fair, many of the blogs were written before Beagleboard_XM existed, so there
was no reason at that time to note the board type, But the voting system may
take care of that (again, over time).

Thoughts?

All fantastic suggestions. I'll note everything you've suggested and
add it to my list of potential wiki changes for the future.

Also, I emailed you privately earlier today, did you get that email?
And are you on #beagle in IRC?

10

Hi Ziggy,

You've raised what I think is an important issue to the future of
Beagleboard/Beaglebone (documentation), and made some well-reasoned
suggestions.

I wonder how many people who've used the eLinux.org site realize it's a
wiki, and they can therefore edit the contents? You have to login in order
to see the "edit" link, so my guess is that a lot of people never thought
about updating the pages themselves.

Interesting, I never would have considered that someone would not know
elinux.org was a wiki.

I don't know how to convert readers to contributors: I guess it's a common
problem for all types of wikis. Maybe it would help if the site prominently
encouraged reader input. I will say that I'm amazed at how helpful people
are on this Google Group. It's rare that a question gets asked without some
kind of response. The willingness to help others definitely exists. It would
be great to see that spirit channeled into a wiki of some sort.

The number of contributions over the last 6 months has actually
sky-rocketted. However, most of the content is specific to
RaspberryPi.

My intent over the next little while is to first add a features
section to the front page that highlights some specific content, much
in the same way that wikipedia.org works. Similarly, I'm working now
to add a planet feed to the site that would allow bloggers to add
their sites feed.

11

I’m glad to see this topic is being revisited ( https://groups.google.com/forum/?fromgroups#!topic/beagleboard/j_rybEhIRY8 ) and gaining some traction. One thing I would like to see added to the wiki is some groundrules and guidelines about contributing to elinux.org. I asked that question of Jason Kridner in the previous thread and never received a reply. I would also make an appeal to make the site more task driven much like this user group ends up being. For example, a link entitled “how do I attach the beagleboard to the internet using the Belkin N150 USB WiFi dongle”, etc, searchable with sensible tags and keywords. I’m not a web programmer, but I’d like to help in any way I can. I certainly have a couple of pages of learnings to add…

12

I'm glad to see this topic is being revisited (
Redirecting to Google Groups )
and gaining some traction. One thing I would like to see added to the wiki
is some groundrules and guidelines about contributing to elinux.org. I asked
that question of Jason Kridner in the previous thread and never received a
reply. I would also make an appeal to make the site more task driven much
like this user group ends up being. For example, a link entitled "how do I
attach the beagleboard to the internet using the Belkin N150 USB WiFi
dongle", etc, searchable with sensible tags and keywords. I'm not a web
programmer, but I'd like to help in any way I can. I certainly have a couple
of pages of learnings to add...

I'll read later today and make sure to reply.

13

What would be beagleboard specific to that? I think it's more specific to the software running on the beagle than the board itself. I bet people running freebsd on beagle wouldn't be able to use the info on that page you describe.
The first rule about embedded linux: it's just linux. Even if you think your platform is special, it usually isn't :slight_smile:

14

I would contend that to limit any “beagleboard” forum to issues that apply to that platform and that platform only would greatly diminish its utility, aside from the practical matter that oftentimes it’s hard to tell if your issue is HW-specific. In any case, all I’m envisioning is a place where all the collective learning contained in this wonderful forum is captured, organized and continuously improved by the community, the well known wikipedia model. To your point, I agree that expanding the scope to encompass the entire embedded linux body of knowledge would be impractical, although the judicious placement of relevant links to this wider body of knowledge would again enhance the wiki’s utility.

15

Hi Wmat,

With respect to elinux.org being understood to be a wiki, I think a higher hurdle for some is having both the confidence to post a page about a subject, or even more difficult, changing someone’s entry (even if it is because the entry has become out of date - rather than the original being wrong). I’m certainly still forming my picture about how things hook together. I have a model in my head as to how it slots together, but that model has been changed more than a few times over the last couple of months. I suspect that this is one of the things that limits participation.

I’d be happy to add some wiki entries, but would benefit from some pre-submission review or discussion to confirm what I think happens is correct on specific subjects. For example, I’m trying to piece together how all of the Graphics elements fit together (OpenGL2, TI SFX SDK, and so on). There appear to be about 6 or 7 parts between the application and the SFX Graphics Accelerator. I’d like to document that as a diagram once I have it straight in my head, but I’m finding it hard to confirm how it all fits together. I would be hesitant about publishing this without review. Perhaps I shouldn’t be, but I suspect this is not an uncommon situation.

Regards
Zigs.

16

There are a lot of replies in this thread and I'll try to keep them in
mind in my reply, but I thought including them all would make my own
reply unreadable.

This topic is not limited to Beagleboard specifically, but I thought it
would be interesting to solicit a discussion here as Beagleboard seems to be
one of the primary boards that introduces people to Open Source Embedded
Development. (and it's my embedded development board of choice).

...and especially embedded Linux, which is why we have such a strong
relationship with the elinux.org wiki that I'd like to grow.

I've spent a lot of the last few months getting up to speed on embedded
development and all that entails (and there's a lot to learn - with the
tools, linux config, applications and variations in the hardware versions).
Reading the various IRC, blogs, groups and websites, there is a wealth of
information, but as has been noted many times, much of it is out of date and
is not relevant in all cases.

This is understood to be an issue, but I think there is a lot of
pushback in various embedded Linux circles towards consolidating
information that often requires specific examples on specific hardware
to be understood sufficiently and no one person putting together a
book or small number of web articles can cover all that there is to
learn. If you want to be part of the solution here, I'd suggest
creating some place-holder articles and campaigning ferociously to
have the experts in this community fill in the blanks. The elinux.org
wiki would be a great place to do such an effort.

I've read many posts from newbies and early developers exclaiming
frustration at what is perceived as lack of documentation and an absense of
a big picture which can help put problems in context. My own experience felt
a bit like Alice falling down the rabbit hole, investigating some problems
just took me deeper and deeper, and I had to learn stuff to a level far
beyond my initial expectation. OpenEmbedded certainly makes the whole
process much easier, but it certainly doesn't appear to be the case that you
can just pick the packages, press build and get a fully working image every
time (and I don't think that should be the expectation).

I don't know if it is falling down a rabbit hole or that you are
opening up a rat hole with this statement.

At the other end of the spectrum, I personally, would like to thank the
gurus/experts who review the updates and provide guidance (note I avoid the
word "support" very deliberately) to help us onto the first rung of the
ladder. These experts must be dedicating a huge portion of their time, and I
for one am grateful for that. I read an interesting e-discussion recently
where someone was airing frustration about the lack of documentation, and
how they could not base a commercial development on this state of affairs.

I'll jump in right here and say that there are many very viable
commercial development paths and different customers *need* to take
different paths.

For many typical TI ARM processor customers, the TI SDK and/or a
commercial Linux provider will be a better path than the software
provided promoted the most on this list and on the BeagleBoard.org
website. It is a shame if such potential customers get confused and
think BeagleBoard.org is meant to serve them directly, since it is
meant to serve a much broader audience. For many other people who buy
BeagleBoards, even those looking to drop one into their product and
even indirectly for the aforementioned customers, the existing
community projects are exactly what they need to solve their problems.
That said, there are many different starting points for good reasons.
If what you want is Ubuntu, then you should note that Ubuntu support
on BeagleBoard and BeagleBone is quite good. If what you want is
Android, ability to leverage Android development knowledge on Beagle
is also quite good and to get support from TI or 3rd parties.

Perhaps what isn't well understood is that BeagleBoard.org is a
constantly evolving community project, not a static product offering.
It is certainly my goal to work towards something that could compete
with any available commercial development platform in every various
software starting point, but some aspects are further along than
others. Perhaps we've grown up enough that we should be setting some
development milestones to be better organized as a community?

There are many different moving vectors by all of the various
participants in the project. I accept the criticism that the
documentation isn't as well organized as it could be, but there is a
tremendous amount of information out there that enable people to solve
problems using the BeagleBoard.org hardware designs. One thing I'd
welcome are some community members motivated enough to outline the
problems to solve and would come back to the many resources, including
the #beagle IRC channel, this mailing list, the various blog posts out
there and Linux documentation resources to seek answers. The best
place to organize and present such information is
Beagleboard:Main Page - eLinux.org and patches to the
http://beagleboard.org website. I'll be working on revamping the
website to feature the eLinux wiki more prominently.

What I've been spending most of my thoughts on is how to organize
learning about developing with embedded Linux on BeagleBoard/Bone as
part of two efforts:
1) Bonescript and the Bone101 presentation that seeks to document how
to perform web UI interaction and Arduino-like hardware interactions
using Linux
2) the ECE497 32-bit Embedded Linux course taught at Rose-Hulman with
materials hosted on the eLinux wiki

Bonescript is definitely a work in progress and doesn't solve enough
problems yet to promote. Ultimately it will be self documenting and
I'm looking at how I can synchronize it to the eLinux wiki as well as
even move the BeagleBoard.org pages into it to make the
BeagleBoard.org website more dynamic. It is hosted on github and
contributions are welcome.

The ECE497 course is more of a start to finish process of getting
familiar with doing embedded Linux development. What I need to do more
promotion of it as a solution to your issues is more people trying it
out and telling me it is accurate and up-to-date. If you are looking
for a set of tutorials to follow, I suggest starting with this set.

The summary of the responses was basically that Open Source is free and you
get what you pay for. It is unsupported, and the developers have better
things to do with their time than write documentation. Users are expected to
roll their sleeves up and read the source code. But there's a considerable
(huge) learning curve for most to get to the point of being able to do this.

Ugh. I want BeagleBoard.org to become a project that makes learning
embedded Linux easy. That isn't a simple problem. I haven't seen an
example of anyone else solving it. Again, where I'll be investing my
personal time is in the two above projects that seek to teach embedded
Linux from various angles. I'm interested in your feedback on those.

I can see both sides of the argument, as someone who has struggled to get
things working and having trundled down a lot of blind alleys, the lack of
documentation and context of some blogs has made me frustrated at times.
However, I don't think that anyone in the community owes me anything. It's
all free, after all.

Good.

So here's the question. Is there a middle ground, tool, process or something
which can be community driven and low impact (certainly not as cumbersome as
documentation), but which helps provide relevant guidance? I'm guessing that
a lot of the same questions are raised time after time, and the guru's must
get a bit bored of answering them (I can almost see the eyes rolling up into
the forehead sometimes and their patience is admirable ;-)).

There are some excellent embedded Linux trainers that are part of the
BeagleBoard.org community and use the boards in their training. If you
have money and no time, I suggest reaching out to them such that you
can get up the curve quicker. Many of them create blog posts or answer
questions on this mailing list for free. Folks like Free Electrons
even publicly host much of their materials for free download. Karim
Yaghmour has provided his Android training materials for free. I
mentioned the ECE497 materials. Those are just some quick ones off the
top of my head.

When people provide answers on this mailing list, they largely
consider the question answered. I know getting all of the information
organized is valuable and several folks in the community make efforts
to aggregate information about various tasks into the eLinux wiki. It
would be great if you would be one of those people and if you would
ask the questions that you feel like aren't well known on this mailing
list.

Many questions
posted also remain unanswered, possibly also because they have been asked so
many times before.

If you see questions go unanswered, feel free to ping me personally. I
see some questions with vague answers, but I don't notice them going
unanswered--though I don't always go back and check all of the history
either.

The advantage of having some better, more reliable guidance is that it
should reduce the number of simple questions, and might reduce the number of
talented folks that drop out completely due to frustration. The more people
that stay productive in the game, the more progress is made by all. One
disadvantage is that making it easier to find solutions may discourage some
from looking deeper into the code and thus may perpetuate the "it should
just work out of the box" myth.

Shouldn't it "just work out of the box"? I agree that not everything
is there and that some aspects of the project require a lot of
learning before becoming sufficiently knowledgable to submit patches
to the shipping distro, the mainline Linux kernel or one of the many
distros that support the BeagleBoard.org boards, but I think I've
missed your point.

So here's some things that I feel would have helped me in my quest:

1) Many blogs were out of date and related to different versions of Angstrom
Dist/Linux kernel/OE version/hardware. Some way to bring the related blogs
together and relate them to the various versions of tools etc would help
guide folks to a solution that would be more likely to work for them. Often
the versions are not recorded in the blog. In my case I was trying to get a
wifi dongle to work and I went down numerous blind alleys - but learnt a lot
on the way. It would be interesting to ask users of the blog to indicate as
to whether or not the procedure worked for them (and record the versions
used). In that way a user could see if the method was considered reliable or
not for their environment (and if not, whether there are common problems). I
guess this would help provide similar statistics as an overnight build
regression test.

Angstrom moves much faster than many other distros making
documentation go out of date more quickly, though all distros have the
issue of documentation becoming stale. My solution is to create
Bonescript as self-documenting and self-testing (though I need to
automate that testing part). I think your point about performing
overnight regression testing is spot on. The need to create automated
regression testing on the documentation, however, is largely spoiled
by the many physical interactions required within many of the
documented steps. This means we often rely on large size of the
community to identify when documentation becomes out of date.

What I'd recommend to you as a solution is for you to place
documentation on the eLinux wiki for the procedure as best you
understand it, then notify this list of any issues you discover on
that wiki. If it is determined that you are out of your mind, then it
is likely that your notification will be our clue to delete the page.
I think it is unlikely that you are out of your mind.

2) When things didn't work, what I often wanted to do, was recreate the same
environment as the blogger had used, to be able to start from a known stable
base. Something that addresses the above might help acheive that.

It would be great if the bloggers would document the image they used.
I had a grand vision of creating a website that would allow annotation
when someone tried the instructions with a various image and if they
worked such that we'd have information to bisect any failures.
Creating the infrastructure has alluded me. In the meantime, why don't
you:
#1) give us good examples on the eLinux wiki of things that you've
tried that *do* work and
#2) ask "smart questions" (google it) regarding blog posts that don't
work and *then* create the eLinux wiki entries using the answers

3) If the above could be done across a number of common tasks, then perhaps
a step by step training course would fall out that goes beyond "Hello World"
to familiarise beginners with the myriad of tools that they will need in the
development arsenal (OE, Git, Linux Configure). I for one, believe I have
found problems and have been unsure about the proper way to submit bug
reports / solutions.

The proper way is to notify this e-mail list. It is
the-one-list-to-rule-them-all. It is the thing that attempts to keep
the BeagleBoard.org community from excessively fragmenting and not
being able to find answers. Bug trackers are great, but shaming me at
regular intervals right here is the way to make things happen.

What other light touch things would have helped people over the early
hurdles to get them to the point where they could contribute. Full
documentation is obviously not an option, but is there something community
driven that could make the mass of data that is already out there more
relevant and more organised, and at the same time add extra validation? Or
(and I fear this may be the case), are the number of variables so large that
the task rapidly becomes unmanageable?

I don't know. I'm looking at doing, roughly in this order:
1) answering technical software questions on this list that aren't
answered by someone more knowledgable in the community,
2) improving what Bonescript walks you through as examples of how to
do development and how that is presented to you from the board and the
web,
3) improving what the ECE497 class materials are able to cover in
terms of learning exercises, and
4) updating BeagleBoard.org to point to more answers generated by the
community and consolidated on the eLinux wiki, perhaps with a few
personally managed pages to clarify information ownership.

Do you think those are the right steps to address your concerns?

17

Hi Wmat,

With respect to elinux.org being understood to be a wiki, I think a higher
hurdle for some is having both the confidence to post a page about a
subject, or even more difficult, changing someone's entry (even if it is
because the entry has become out of date - rather than the original being
wrong). I'm certainly still forming my picture about how things hook
together. I have a model in my head as to how it slots together, but that
model has been changed more than a few times over the last couple of months.
I suspect that this is one of the things that limits participation.

Can you create suggestions on the comment pages and come to this list
to review your thoughts?

I'd be happy to add some wiki entries, but would benefit from some
pre-submission review or discussion to confirm what I think happens is
correct on specific subjects. For example, I'm trying to piece together how
all of the Graphics elements fit together (OpenGL2, TI SFX SDK, and so on).
There appear to be about 6 or 7 parts between the application and the SFX
Graphics Accelerator. I'd like to document that as a diagram once I have it
straight in my head, but I'm finding it hard to confirm how it all fits
together. I would be hesitant about publishing this without review. Perhaps
I shouldn't be, but I suspect this is not an uncommon situation.

That makes sense. I don't think it is too much noise to seek reviews
here. I'd further suggest getting on #beagle
(http://beagleboard.org/chat) and soliciting at least one individual
to go through the step-by-step for you. If the steps are reasonable,
you'll find someone to try them. If they are not, you'll get
frustrated and go away.

18

Hi Jason,

Thanks for taking the time with such a detailed answer. I’ll pick out the key sentences that I’d like to respond to make the text more readable.

Firstly, by far the most important one for me:

I accept the criticism that the documentation isn’t as well organized as it could be…

Absolutely no criticism was intended. What is offered by the experts is above and beyond the call of duty, and I fully understand that you folks have better things to do, which quite frankly are much more valuable. By far the better model for me would be that the newbies document methods as they find them, and that these are then reviewed by the experts. In this way the newbies will write it from the perspective of the learner, and will contribute back to the community which is guiding them. I’ve also learnt from this discussion that that place is elinux.org, and I hope I can contribute in the future in the right place.

I don’t know if it is falling down a rabbit hole or that you are opening up a rat hole with this statement.

Feel like I’ve stepped on a landmine, but am not sure why. I’ve come from a hardware backgound with some FPGA skills and some scripting, simple C and assembler background. Being able to build an entire linux distribution at the press of a button is both amazing and frightening at the same time. For someone like me, when it works, it’s great, but when it doesn’t it’s kind of daunting. For example, I was totally unaware of autoconfig until recently. But when I couldn’t get XBMC to build with the latest recipe, I had to hunt down and learn about it to find the problem (a problem with a recursive ccache statement in the generated configure script). A great learning step forwards, but progress towards my end goal is slow due to the numerous detours. I can’t imaging how long it would have taken me to get to where I am now without the framework of something like OpenEnbedded (and OpenEmbedded-core provides a much more understandable structure).

I’ll jump in right here and say that there are many very viable commercial development paths and different customers need to take different paths.

I agree. I’m regretting citing the commercial comment as this wasn’t my angle. I was only trying to highlight the difference in some unrealistic expectations and the current reality, and to then try and explore the middle ground. That is to say, debate whether there is another way of addressing the problem. For me the problem is how to deal with the legacy, out-of-date information that pervades and slows down progress. Not remove it, but tag it such that folks can assess the relevance to them. I didn’t want to assume that my perception of the problem was the only one, and had hoped that I might solicit more responses from learners like myself to get a range of ideas on how to tackle the problem(s). I also had a (probably unreasonable) hope that someone might suggest an existing tool for addressing this problem of information going stale.

What I’ve been spending most of my thoughts on is how to organize learning about developing with embedded Linux on BeagleBoard/Bone as part of two efforts:

Many thanks for the pointers to the various learning resources. Some I have seen, others I will take a look at. Once there is a foundation, I find the best way of learning is to do. My usual approach is to dream up a project that I want to acheive, and learn the pieces as I go along ( a model I’m sure everyone is familiar with). Where I find it comes unstuck is where I hit the big problems that leave me static for days at a time, or worse going backwards. Morale is low after those events, but small victories help get me through those periods, and being able to zero in on the relevant information would help.

As you have said, there is a lot to Linux and the neccessary environment around it. If I look back a few months, had I have known all of the different threads I’d need (U-boot, Git, AutoConfig, OE, Drivers, Linux structure, Graphics Drivers, Network Drivers…), I would have been better prepared. I think a key balance is to prepare the expectations of new folks realistically, without scaring them. The fact that all of these different aspects are also changing rapidly just adds to the problem. Don’t get me wrong, these are essential skills and they need to be learnt, but there are many detours on the way to embedded linux development.

Perhaps what isn’t well understood is that BeagleBoard.org is a constantly evolving community project, not a static product offering.

Absolutely clear to me. and following this discussion, more clear that some way of tracking the relevance/staleness of information would be desirable.

. I want BeagleBoard.org to become a project that makes learning embedded Linux easy. That isn’t a simple problem.

You set yourself a very challenging goal, and I think you should be very proud of what has been acheived. I’ve definitely benefitted and would like to contribute back.

It would be great if you would be one of those people and if you would ask the questions that you feel like aren’t well known on this mailing list.

I fear the questions I have at the moment may have been asked a hundred times before, but just in a slightly different form.

Creating the infrastructure has alluded me. In the meantime, why don’t you:
#1) give us good examples on the eLinux wiki of things that you’ve tried that do work and
#2) ask “smart questions” (google it) regarding blog posts that don’t work and then create the eLinux wiki entries using the answers

Will do.

  1. updating BeagleBoard.org to point to more answers generated by the community and consolidated on the eLinux wiki, perhaps with a few personally managed pages to clarify information ownership.

I really am very grateful for the responses from the experts, I know from the names that the great and the good of the community have responded and this clearly reflects the enthusiasm and dedication you have to this wonderful community.
There are tools and websites that I clearly had not drilled down far enough into (for which I apologise) and there are forums and wikis and blogs, and I feel more directed to know where to focus my efforts to participate more effectively.

I do, though, think that there is room for a different widget/app/bolt-on which might help deal directly with the stale information problem, which this discussion has only re-inforced in me is a key problem. This would be meant to compliment and support the existing tools as an adjoining function. I’ll ponder more on this.

I would also welcome comments from other newbies on what they perceive the early hurdles to be. Are they different to mine?

Once again, many thanks for your valuable time.

Regards
Zigs