[oe] Documentation problems

[Paul Menzel]

Dear Rainer,


thank you for sharing you view.


Am Mittwoch, den 30.11.2011, 16:49 +0100 schrieb Rainer Koenig:

> Am 27.11.2011 03:40, schrieb Tom Rini:

[…]

> 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.

»familiar« does not mean that they are not able to understand it.

> 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.

Unfortunately of lot of the responds miss the point. Instead of finding
the reason why the reason for documentation is lacking it is discussed
instead of WikiMedia is feasible or not although it has been there for a
long time and it looks like it has failed. The point that documentation
making has to be as easy as possible is agreed on by everyone.

So please let us be constructive and share your comments in the sub
thread »Re: [oe] [RFC] Documentation problems and future plans«.

> 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.

Tom King seems to have to acknowledge each registration. Please contact
him about this.

> 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.

If you hit the problem probably it has not been solved. Also you can
search the commit log (`git log`) easily for changes in the Samba
recipes.

> 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.

As Koen wrote. It was not used anymore and probably a bad thing to not
shut down the Bugzilla instance immediately.

> 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".

See Koen’s response.

The actual question is still how the developers feel. And as far as I
know nobody has missed it. It looks like an email interface is a
requisite for most of them.

> 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?

See above and the whole thread. And suggestions on how to get things
done are very welcome.

> 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.

One difference is that Yocto is backed by corporations paying folks for
documentation. And actually OE-core and Yocto should be pretty much
aligned. 

> 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.

I thought that was this topic of this thread the whole time. I have to
agree that it diverged into a different direction than I hoped for.


Thanks,

Paul
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://lists.openembedded.org/pipermail/openembedded-devel/attachments/20111130/29e9c17f/attachment-0002.sig>