[oe] Documentation problems

[Rainer Koenig]

Hi Tom,

Am 27.11.2011 03:40, schrieb Tom Rini:
> As things stand today, the wiki is out of date and a number of folks
> refuse to work on it.  Using things like "It's all text!" for firefox
> only go so far and don't solve problems like people just avoiding
> documentation anyhow.

I've read the postings in this tread and got something between amused 
and angry. Hitting the embedded Linux world in April I'm still a 
newcomer to this and so I can share my impressions with you, telling how 
OpenEmbedded and other projects look to a new user.

I started with OE classic since this is where the main page in the wiki 
leads you to. Then I failed and learned about OE core, found the pages 
and tried again, still failing. I printed out the OE documentation to 
learrn, that many things that would be interesting are still as "ToDo" 
or "Fixit" and that the docs quite outdated.

During my attempts I found out, that certain versions of bitbake are 
showing errros on some recipes while other versions don't do. So I tried 
to read the Changelog of bitbake and saw, that the most recent entry was 
from 2009.

Then I tried to see if problems that I'm encountering are "known issues" 
so that I can find it in bugzilla. And I learned that you gave up 
Bugzilla for tracking bugs on the mailing list. Ouch!!!

Meanwhile someone advised me to look at the Yocto project. The docs 
there looked prettier, even as they are just HTML pages. They also have 
a wiki and bugs are managed inside a Bugzilla.

I'm still reading the docs from both OE and Yocto, together they helped 
me to climb up the very steep learning curve.

The things that make me amused is when I read comments like

----8<-snip------------
And developers are not familiar with
MediaWiki or most of the time hate it to not be able to use their
favorite editor and to use a Web interface.
----8<-snip------------

or

----8<-snip---------
Just having to edit a text file in an editor and
commit this change is easier than working with a Web browser.
----8<-snip---------

Seriously guys, if you are a developer and you are able to understand 
the structure in OE and what bitbake does, then you should be able to 
understand the Wikimedia engine as well. And if you want to avoid a 
web-editor then copy/paste the stuff to your favorite editor and do it 
there. Complaining about the tool you need to use sounds like a lame 
excuse for an software engineer.

Of course, the Wikimedia engine offers advanced methods like categories 
to tag stuff but even that can be learned in short time. So I really 
doubt that the reason for not documenting is the Mediawiki engine.

The other problem that I see when trying to contribute: This morning I 
registered my account "rakoenig". Now, 7 hours later I'm still not able 
to edit anything and I have no idea how the process looks like to get 
write privileges. On the other hand, when I was doing the same in the 
Yocto wiki I was instantly able to write pages there.

Now for the bugtracking thing. Yes, I think, that bugtracking is part of 
a project documentation and I would like to be able to find a bug and 
see a status. When you handle bugs on a mailing list I'm forced to use 
to search the archives for that bug and then I might find a thread that 
then has a lose end like

--8<-snip------
Will look again tomorrow. Go to bed.
--8<-snip------

That was the latest info on a bug when building samba and so far nobody 
knows if this bug is solved or not.

The funny thing is that when I first asked why you changed bug tracking 
to do it with a mailing list I was adivsed do search in the archives for 
that discussion. Searching the archives revealed that a lot of bugs hit 
Bugzilla and nobody took care of them. So, from my external point of 
view the decision was "Bugzilla is actually a mess, so lets try 
something else like the mailing list for bugtracking".

And hey, here we go... this thread is here because the wiki is out of 
date and we need to do...what? Switching to a new tool to confuse even 
more users? Or get the things done that need to be done?

Just look at Yocto. From my point of view it looks much smarter because
they have a bugtracker and post even statistics of their bugs which 
gives me the impression that their concern is improving qualitiy of 
their recipes.

They have a good documentation that seems to get updated frequently, 
makes a good impression.

They seem to have a roadmap for the future and do planned work.

Compared to this OE (core) seems like a bunch of developers working on 
the bleeding edge of embedded Linux and don't document much because 
*they* understand what they are doing. Unfortunately a lot of (new) 
users don't understand it and would urgently need a good documentation.

Sorry for the maybe harsh words, but I really want to show you how OE 
looks to somebody approaching it. And of course I would like to help 
improving the docs, but for that OE needs a clear documentation policy 
and a process how to do and enforce that.

Best regards
Rainer
--