Documentation problems

Documentation problems

[Tom Rini]

Hey all,

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.

Paul Menzel has mentioned that ikiwiki has been mentioned before and
that lets us have the website in a repository.  Do folks have other
ideas?

-- 
Tom

Re: [RFC] Documentation problems and future plans

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 1786 bytes --]

Dear everyone,


Am Samstag, den 26.11.2011, 19:40 -0700 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.

the Special Pages page [1] has interesting information. For example you
can get an overview of the recent changes in the Wiki [2].

> Paul Menzel has mentioned that ikiwiki has been mentioned before and
> that lets us have the website in a repository.  Do folks have other
> ideas?

Before the implementation is discussed, could we decide what
documentation we need and what is possible to maintain in the long run?
Avoiding maintenance and duplicate efforts should be the objective.

1. User manual
2. FAQ
3. README
4. Guidelines (Commit, patch, style)
5. Getting started document (could be included in 1.)
6. Git usage (a lot of existing documentation for that one elsewhere) or
can be put in a file `HACKING`.
7. …

Formatted in a markup language like Markdown those could be converted to
HTML easily.

The second question is, is OE-core documented in the OE wiki or for
example at the Yocto project?

To get users started we could also recommend to use the Ȧngström scripts
or to take a look at the Yocto project, i. e. just point to
distributions being well documented.

They have a Wiki already [3] and we could decide to use that instead. Or
we could say to use use the Wiki at eLinux.org [4].


Thanks,

Paul


[1] http://www.openembedded.org/wiki/Special:SpecialPages
[2] http://www.openembedded.org/wiki/Special:RecentChanges
[3] https://wiki.yoctoproject.org/wiki/Main_Page
[4] http://elinux.org/Main_Page

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: Documentation problems

[Paul Eggleton]

On Saturday 26 November 2011 19:40:48 Tom Rini wrote:
> As things stand today, the wiki is out of date and a number of folks
> refuse to work on it. 

The question is why do they refuse to work on it? And would throwing out our 
current wiki and setting up something completely new and different actually 
solve the issue? I suspect the problem is more that people feel they can't 
make time for writing documentation or simply aren't interested.

For a long time because of spam problems it was impossible for anyone outside 
a set few to edit the wiki. I thought this was resolved already but I could be 
wrong.

I think the best thing would be if we could come up with a set of proposed 
topics to cover and a basic structure and get volunteers to start working on 
each item.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: Documentation problems

[Koen Kooi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Op 27-11-11 03:40, Tom Rini schreef:
> Hey all,
> 
> As things stand today, the wiki is out of date and a number of folks 
> refuse to work on it.

Does it actually need to be a wiki? Or rather: do web edits need to show up
immediately?

> Paul Menzel has mentioned that ikiwiki has been mentioned before and that
> lets us have the website in a repository.  Do folks have other ideas?

I really like the idea of storing the content in git since it gives us 2
things we need for documentation: backups and a pull model.

regards,

Koen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (Darwin)
Comment: GPGTools - http://gpgtools.org

iEYEARECAAYFAk7SWs8ACgkQMkyGM64RGpG2pQCdEJpV4Qx8QiE12s1GgHA1JCaV
I7YAoIQxzH9Io1NcddPecgOK8HDWRU+3
=jo70
-----END PGP SIGNATURE-----

Re: [RFC] Documentation problems and future plans

[Chris Larson]

On Sun, Nov 27, 2011 at 2:58 AM, Paul Menzel
<paulepanter@users.sourceforge.net> wrote:
> Am Samstag, den 26.11.2011, 19:40 -0700 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.
>
> the Special Pages page [1] has interesting information. For example you
> can get an overview of the recent changes in the Wiki [2].
>
>> Paul Menzel has mentioned that ikiwiki has been mentioned before and
>> that lets us have the website in a repository.  Do folks have other
>> ideas?
>
> Before the implementation is discussed, could we decide what
> documentation we need and what is possible to maintain in the long run?
> Avoiding maintenance and duplicate efforts should be the objective.

This is a very good idea.

> 1. User manual
> 2. FAQ
> 3. README
> 4. Guidelines (Commit, patch, style)
> 5. Getting started document (could be included in 1.)
> 6. Git usage (a lot of existing documentation for that one elsewhere) or
> can be put in a file `HACKING`.

This is a good idea. I think we should extend this beyond just git
command info and references to existing git documentation, by adding
actual snippets of shell showing what to do to accomplish several
common development tasks -- example workflows.

> 7. …

7. Troubleshooting Guide

8. Tips & Tricks - these could be more advanced and unusual things
which aren't suitable for an FAQ, but which nonetheless can be quite
helpful if you're in particular situations.

> Formatted in a markup language like Markdown those could be converted to
> HTML easily.

Agreed, Markdown or RST would lovely.

> The second question is, is OE-core documented in the OE wiki or for
> example at the Yocto project?
>
> To get users started we could also recommend to use the Ȧngström scripts
> or to take a look at the Yocto project, i. e. just point to
> distributions being well documented.
>
> They have a Wiki already [3] and we could decide to use that instead. Or
> we could say to use use the Wiki at eLinux.org [4].
-- 
Christopher Larson
clarson at kergoth dot com
Senior Software Engineer, Mentor Graphics

Re: Documentation problems

[Chris Larson]

On Sun, Nov 27, 2011 at 7:29 AM, Paul Eggleton
<paul.eggleton@linux.intel.com> wrote:
> On Saturday 26 November 2011 19:40:48 Tom Rini wrote:
>> As things stand today, the wiki is out of date and a number of folks
>> refuse to work on it.
>
> The question is why do they refuse to work on it? And would throwing out our
> current wiki and setting up something completely new and different actually
> solve the issue? I suspect the problem is more that people feel they can't
> make time for writing documentation or simply aren't interested.

Personally, I'm quite interested in helping to improve the
documentation, but the wiki has degraded to the point where I wouldn't
even know where to begin.

-- 
Christopher Larson
clarson at kergoth dot com
Senior Software Engineer, Mentor Graphics

Re: Documentation problems

[Frans Meulenbroeks]

What is the problem with being it a wiki (probably with authorized users to
avoid spam).

I'd say let everyone who wants to contribute.
If someone makes a mistake it can easily be corrected and/or reverted, and
if someone messes things up on purpose and/or creates more bad than good
such a (non)contributor can be banned.

Disadvantage of a pull model is:
- more difficult to make changes (e.g. if I see a typo in a wiki and I have
write permission, I'll fix it; however if it invokes checking out a file,
make the edit, commit it, mail a pull request, most likely I'll decide it
is not worth the effort
- more administrative workload (that is probably better spent on actually
doing things).
- It sends out a message of distrust. Not really a good way to create
involvement.

One might feel that it improves quality; then again also in a wiki one can
review and improve (or revert) changes.

As far as I see it we are all adults (at least I think so) all interested
in improving OE so no unnecessary barriers should be raised.

Frans.

PS: it is quite possible to backup a wiki (and I hope this is done at
regular intervals with our wiki). Also all edits are recorded so they can
always be tracked back and (if needed) undone.

Re: Documentation problems

[Paul Eggleton]

On Sunday 27 November 2011 17:58:00 Frans Meulenbroeks wrote:
> What is the problem with being it a wiki (probably with authorized users to
> avoid spam).
> 
> I'd say let everyone who wants to contribute.
> If someone makes a mistake it can easily be corrected and/or reverted, and
> if someone messes things up on purpose and/or creates more bad than good
> such a (non)contributor can be banned.
> 
> Disadvantage of a pull model is:
> - more difficult to make changes (e.g. if I see a typo in a wiki and I have
> write permission, I'll fix it; however if it invokes checking out a file,
> make the edit, commit it, mail a pull request, most likely I'll decide it
> is not worth the effort
> - more administrative workload (that is probably better spent on actually
> doing things).
> - It sends out a message of distrust. Not really a good way to create
> involvement.
> 
> One might feel that it improves quality; then again also in a wiki one can
> review and improve (or revert) changes.
> 
> As far as I see it we are all adults (at least I think so) all interested
> in improving OE so no unnecessary barriers should be raised.
> 
> Frans.
> 
> PS: it is quite possible to backup a wiki (and I hope this is done at
> regular intervals with our wiki). Also all edits are recorded so they can
> always be tracked back and (if needed) undone.

I agree with all of this. We shouldn't be putting more barriers up to 
contributing to the documentation - there are already enough.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: Documentation problems

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 2041 bytes --]

Am Sonntag, den 27.11.2011, 17:06 +0000 schrieb Paul Eggleton:
> On Sunday 27 November 2011 17:58:00 Frans Meulenbroeks wrote:
> > What is the problem with being it a wiki (probably with authorized users to
> > avoid spam).
> > 
> > I'd say let everyone who wants to contribute.
> > If someone makes a mistake it can easily be corrected and/or reverted, and
> > if someone messes things up on purpose and/or creates more bad than good
> > such a (non)contributor can be banned.
> > 
> > Disadvantage of a pull model is:
> > - more difficult to make changes (e.g. if I see a typo in a wiki and I have
> > write permission, I'll fix it; however if it invokes checking out a file,
> > make the edit, commit it, mail a pull request, most likely I'll decide it
> > is not worth the effort
> > - more administrative workload (that is probably better spent on actually
> > doing things).
> > - It sends out a message of distrust. Not really a good way to create
> > involvement.
> > 
> > One might feel that it improves quality; then again also in a wiki one can
> > review and improve (or revert) changes.
> > 
> > As far as I see it we are all adults (at least I think so) all interested
> > in improving OE so no unnecessary barriers should be raised.
> > 
> > Frans.
> > 
> > PS: it is quite possible to backup a wiki (and I hope this is done at
> > regular intervals with our wiki). Also all edits are recorded so they can
> > always be tracked back and (if needed) undone.
> 
> I agree with all of this. We shouldn't be putting more barriers up to 
> contributing to the documentation - there are already enough.

Only Koen brought up the idea of the pull model. By itself, ikiwiki also
allows Web edits [1].

Additionally, you have not addressed the point that reality shows, that
not a lot of people write documentation and use it. The best way to
“enforce” this is to add documentation with the corresponding change.


Thanks,

Paul


[1] http://ikiwiki.info/
    (just click on edit)

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: Documentation problems

[Paul Eggleton]

On Sunday 27 November 2011 19:38:39 Paul Menzel wrote:
> Only Koen brought up the idea of the pull model. By itself, ikiwiki also
> allows Web edits [1].

Yes but what benefit do we get by changing the system? Only that the backend 
changes to git? Given that MediaWiki is familiar to many (thanks to Wikipedia) 
I would be hesitant to replace it with anything less widely understood.

> Additionally, you have not addressed the point that reality shows, that
> not a lot of people write documentation and use it. The best way to
> “enforce” this is to add documentation with the corresponding change.

I'm not sure I understand what you mean here. If you're suggesting that we 
will be able to force people to write changes for the documentation together 
with their changes to the code, I think there are two problems with this: 
  (1) it assumes that we already have complete documentation for the current 
state of the code;
  (2) given that writing meaningful commit messages is a challenge for many 
contributors, you're going to have a very difficult time getting people to write 
documentation for their changes as well.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: Documentation problems

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 1979 bytes --]

Am Sonntag, den 27.11.2011, 18:56 +0000 schrieb Paul Eggleton:
> On Sunday 27 November 2011 19:38:39 Paul Menzel wrote:
> > Only Koen brought up the idea of the pull model. By itself, ikiwiki also
> > allows Web edits [1].
> 
> Yes but what benefit do we get by changing the system? Only that the backend 
> changes to git? Given that MediaWiki is familiar to many (thanks to Wikipedia) 
> I would be hesitant to replace it with anything less widely understood.

Everything is in one place. 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.

Maybe a survey should be held. It is work in the beginning but would pay
back in the end since this infrastructure should be used for a while. Or
we just try it out.

> > Additionally, you have not addressed the point that reality shows, that
> > not a lot of people write documentation and use it. The best way to
> > “enforce” this is to add documentation with the corresponding change.
> 
> I'm not sure I understand what you mean here. If you're suggesting that we 
> will be able to force people to write changes for the documentation together 
> with their changes to the code, I think there are two problems with this: 
>   (1) it assumes that we already have complete documentation for the current 
> state of the code;

Then people could update that part in one go or should at least add a
TODO somewhere.

>   (2) given that writing meaningful commit messages is a challenge for many 
> contributors, you're going to have a very difficult time getting people to write 
> documentation for their changes as well.

That is our choice to make. Either we want good documentation. Then we
have to make this a requirement and contributors have to deal with that
but will get help from the list too. Or we do not enforce this and
probably the documentation will be lacking.


Thanks,

Paul

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: Documentation problems

[Frans Meulenbroeks]

Generally speaking writing documentation is difficult and a task not liked
by most sw developers (me included).
People should be encouraged and it should be as easy as possible.
The more difficult it is, the less likely it is people will do it.

Then again I am not too sure what we need, given the yocto documentation.

BTW and if a certain part of the wiki is for a specific purpose (e.g.
related to a distro): in most wiki's it is possible to restrict access to
certain pages to a specific group.
Then again that all needs to be managed....

Frans

Re: Documentation problems

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 886 bytes --]

Am Sonntag, den 27.11.2011, 22:49 +0100 schrieb Frans Meulenbroeks:
> Generally speaking writing documentation is difficult and a task not liked
> by most sw developers (me included).
> People should be encouraged and it should be as easy as possible.
> The more difficult it is, the less likely it is people will do it.

My point exactly! Just having to edit a text file in an editor and
commit this change is easier than working with a Web browser.

> Then again I am not too sure what we need, given the yocto documentation.

See the other sub thread.

> BTW and if a certain part of the wiki is for a specific purpose (e.g.
> related to a distro): in most wiki's it is possible to restrict access to
> certain pages to a specific group.

Sure. But has this been necessary in the past?

> Then again that all needs to be managed....

True.


Thanks,

Paul

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: Documentation problems

[Tom Rini]

On Sun, Nov 27, 2011 at 8:44 AM, Koen Kooi <koen@dominion.thruhere.net> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Op 27-11-11 03:40, Tom Rini schreef:
>> Hey all,
>>
>> As things stand today, the wiki is out of date and a number of folks
>> refuse to work on it.
>
> Does it actually need to be a wiki? Or rather: do web edits need to show up
> immediately?

If spam is eliminated, does it still matter, today?

>> Paul Menzel has mentioned that ikiwiki has been mentioned before and that
>> lets us have the website in a repository.  Do folks have other ideas?
>
> I really like the idea of storing the content in git since it gives us 2
> things we need for documentation: backups and a pull model.

The number one thing we lack today is people willing to document.
Everyone, myself included, who has said we need X done to the public
documentation today, has generally found a point at which they stop
wanting to keep things up to date.  Why?  What would change that?
Does anyone reading this know people that _like_ editing wikis?  Can
we ask them what keeps them engaged in the process?

-- 
Tom

Re: Documentation problems

[Chris Verges]

On Sun, Nov 27, 2011 at 9:11 PM, Tom Rini <tom.rini@gmail.com> wrote:

> Does anyone reading this know people that _like_ editing wikis?  Can
> we ask them what keeps them engaged in the process?
>

Hi Tom,

This is an excellent discussion.  As someone interested in seeing some good
documentation come out of the OE project, consider that documentation is
really the way that users first interact with the software.  If the
documentation is poor, the user will more than likely seek another project.
 But if the documentation helps explain things well, the user will be able
to start interacting with the software and/or code more quickly.

Some consider a "necessary evil," but I prefer to think of it as "the
gateway to the product."  I actually do find documenting my designs and
code to be useful, as I find I can't keep track of as many things the older
I get.  :-)

On that note, as a user of OE for the past 5 years, I want to thank you ALL
for producing a great piece of software.  It's revolutionized how I start
embedded projects, and is one of those "essential" tools in my war chest.
 The "classic" docs were decent enough, but even as someone with 5 years of
OE experience, I'm having problems figuring out the new scheme fully.  I've
been waiting silently to read any docs that are produced, in fact.

I'm happy to help document, but obviously would need some knowledge
transfer to make that happen.  Catch-22, eh?

Thanks again,
Chris

Re: Documentation problems

[Koen Kooi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Op 28-11-11 06:11, Tom Rini schreef:
> On Sun, Nov 27, 2011 at 8:44 AM, Koen Kooi <koen@dominion.thruhere.net>
> wrote:
>> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
>> 
>> Op 27-11-11 03:40, Tom Rini schreef:
>>> Hey all,
>>> 
>>> As things stand today, the wiki is out of date and a number of folks 
>>> refuse to work on it.
>> 
>> Does it actually need to be a wiki? Or rather: do web edits need to
>> show up immediately?
> 
> If spam is eliminated, does it still matter, today?

Ever since OE was founded the information in the wikis has been terrible.
The information in the docbook was accurate, but didn't cover everything.


>>> Paul Menzel has mentioned that ikiwiki has been mentioned before and
>>> that lets us have the website in a repository.  Do folks have other
>>> ideas?
>> 
>> I really like the idea of storing the content in git since it gives us
>> 2 things we need for documentation: backups and a pull model.
> 
> The number one thing we lack today is people willing to document.

I'd change that to "knowledgable people"

> Everyone, myself included, who has said we need X done to the public 
> documentation today, has generally found a point at which they stop 
> wanting to keep things up to date.  Why?  What would change that?

I stopped working on the OE wiki because I couldn't keep up with people
adding anecdotal, but misleading information into it.

> Does anyone reading this know people that _like_ editing wikis?  Can we
> ask them what keeps them engaged in the process?

People in general like editing wikis, yes. The problem with OE is that it is
such niche product and has a steep learning curve as well. It does not lend
itself to drive-by editing like e.g. wikipedia.

How about this:

Proposal a:

1) fork the poky/yocto docbook based manual
2) run a sed script to change it to an OE branded version
3) convert it to a wiki

proposal b:

1) fork the poky/yocto docbook based manual
2) run a sed script to change it to an OE branded version
3) put it in git, webpages get updated with a git-hook

If people want to use a webbrowser to edit it:
https://github.com/blog/844-forking-with-the-edit-button
If we have setup the github mirror correctly the pull request will arrive on
the mailinglist automatically.

regards,

Koen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (Darwin)
Comment: GPGTools - http://gpgtools.org

iEYEARECAAYFAk7TUvoACgkQMkyGM64RGpGqZACgoputgxl8LxHT0bipoA0gdWpV
kzEAnA3mTcKxrfsH3a4M1jTnGHACa6VL
=PMji
-----END PGP SIGNATURE-----

Re: Documentation problems

[Phil Blundell]

On Sat, 2011-11-26 at 19:40 -0700, Tom Rini wrote:
> 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.
> 
> Paul Menzel has mentioned that ikiwiki has been mentioned before and
> that lets us have the website in a repository.  Do folks have other
> ideas?

I guess it depends what documentation you are thinking of exactly.

Bitbake and oe-classic both have their own user manuals written in
Docbook.  I think Poky has something similar which might be more or less
directly applicable to oe-core.  If the objective is to create a high
quality user guide then I think that starting from some combination of
these (and continuing in the same format) is probably the right
approach.

It would be fairly straightforward (modulo TSC regulatory requirements)
to set up a git repository on oe.org to hold the documentation and
arrange for interested folks to have write access to it.  

p.

Re: Documentation problems

[Richard Purdie]

On Mon, 2011-11-28 at 10:30 +0000, Phil Blundell wrote:
> On Sat, 2011-11-26 at 19:40 -0700, Tom Rini wrote:
> > 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.
> > 
> > Paul Menzel has mentioned that ikiwiki has been mentioned before and
> > that lets us have the website in a repository.  Do folks have other
> > ideasPeople could even contribute to those pieces of documentation?
> 
> I guess it depends what documentation you are thinking of exactly.
> 
> Bitbake and oe-classic both have their own user manuals written in
> Docbook.  I think Poky has something similar which might be more or less
> directly applicable to oe-core.  If the objective is to create a high
> quality user guide then I think that starting from some combination of
> these (and continuing in the same format) is probably the right
> approach.

The Yocto documentation effortI'd really love it if we could find a way
for OE and Yocto to share the documentation.
 is aiming at a kind of "bookshelf" approach so that there are manuals
for different parts of the system. 

Yocto has a tech writer dedicated to working on the docs (cc'd, hi
Scott). He's sometimes not able to directly write the deeply technical
content but he is more than happy to take contributions to the manuals
and edit them together to ensure consistent style, ordering and indexing
and so forth. 

We've had a few challenges in finding ways for Scott to be able to work
on docs in an "open source" way using git+docbook as its a little
different from some of his previous work but we're getting there. This
is one of the reasons we have the docs repository separate at the moment
since it simplifies some of Scott's work.

Rather than fork off the Yocto docs for OE's needs, it would be nice to
see if there was a way we could share the documentation.

Cheers,

Richard

Re: Documentation problems

[Otavio Salvador]

On Mon, Nov 28, 2011 at 09:07, Richard Purdie <
richard.purdie@linuxfoundation.org> wrote:

> Rather than fork off the Yocto docs for OE's needs, it would be nice to
> see if there was a way we could share the documentation.
>

I fully agree with that.

The work would be much easier if all that could be shared.

AFAIK, using docbook it is possible to use macros to expand for branding
and also conditional to output text so this could be done in a single
repository.

-- 
Otavio Salvador                             O.S. Systems
E-mail: otavio@ossystems.com.br  http://www.ossystems.com.br
Mobile: +55 53 9981-7854              http://projetos.ossystems.com.br

Re: Documentation problems

[Denis 'GNUtoo' Carikli]

Also the current wiki lacks a license.
(when you edit it says "see Openembedded.org:Copyrights for details" but that 
page points nowehre)

Denis.

Re: Documentation problems

[Philip Balister]

On 11/28/2011 06:16 AM, Otavio Salvador wrote:
> On Mon, Nov 28, 2011 at 09:07, Richard Purdie <
> richard.purdie@linuxfoundation.org> wrote:
> 
>> Rather than fork off the Yocto docs for OE's needs, it would be nice to
>> see if there was a way we could share the documentation.
>>
> 
> I fully agree with that.
> 
> The work would be much easier if all that could be shared.
> 
> AFAIK, using docbook it is possible to use macros to expand for branding
> and also conditional to output text so this could be done in a single
> repository.
> 

We need to be really careful how all the pieces get branded. There is
way too much confusion already, without referring people to the "Yocto
Instructions" to use OE-core + layers.

Philip

Re: Documentation problems

[Philip Balister]

On 11/28/2011 08:33 AM, Philip Balister wrote:
> On 11/28/2011 06:16 AM, Otavio Salvador wrote:
>> On Mon, Nov 28, 2011 at 09:07, Richard Purdie <
>> richard.purdie@linuxfoundation.org> wrote:
>>
>>> Rather than fork off the Yocto docs for OE's needs, it would be nice to
>>> see if there was a way we could share the documentation.
>>>
>>
>> I fully agree with that.
>>
>> The work would be much easier if all that could be shared.
>>
>> AFAIK, using docbook it is possible to use macros to expand for branding
>> and also conditional to output text so this could be done in a single
>> repository.
>>
> 
> We need to be really careful how all the pieces get branded. There is
> way too much confusion already, without referring people to the "Yocto
> Instructions" to use OE-core + layers.

Just to be really clear .....

Also, not I am not opposed to a unified documentation set, just that it
is clear to people what things are called.

Philip

Re: Documentation problems

[Paul Eggleton]

On Sunday 27 November 2011 22:11:00 Tom Rini wrote:
> The number one thing we lack today is people willing to document.
> Everyone, myself included, who has said we need X done to the public
> documentation today, has generally found a point at which they stop
> wanting to keep things up to date.  Why?  What would change that?
> Does anyone reading this know people that _like_ editing wikis?  Can
> we ask them what keeps them engaged in the process?

FWIW I do like editing wikis - certainly more than I like editing things 
written in DocBook at least.

It's true our wiki contains a *lot* of outdated or incomplete information. We 
could do a lot just by marking pages as out-of-date or irrelevant (via 
categories?) and then updating or deleting them assuming people agree. I'm 
happy to start working on this assuming we aren't going to throw the whole 
thing out.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: Documentation problems

[Koen Kooi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Op 28-11-11 14:36, Philip Balister schreef:
> On 11/28/2011 08:33 AM, Philip Balister wrote:
>> On 11/28/2011 06:16 AM, Otavio Salvador wrote:
>>> On Mon, Nov 28, 2011 at 09:07, Richard Purdie < 
>>> richard.purdie@linuxfoundation.org> wrote:
>>> 
>>>> Rather than fork off the Yocto docs for OE's needs, it would be
>>>> nice to see if there was a way we could share the documentation.
>>>> 
>>> 
>>> I fully agree with that.
>>> 
>>> The work would be much easier if all that could be shared.
>>> 
>>> AFAIK, using docbook it is possible to use macros to expand for
>>> branding and also conditional to output text so this could be done in
>>> a single repository.
>>> 
>> 
>> We need to be really careful how all the pieces get branded. There is 
>> way too much confusion already, without referring people to the "Yocto 
>> Instructions" to use OE-core + layers.
> 
> Just to be really clear .....
> 
> Also, not I am not opposed to a unified documentation set, just that it 
> is clear to people what things are called.

I started composing an email listing a lot of the phrases we need to avoid
("yocto builds <foo>"), but I deleted it since previous attempts have been
met with deafening silence. As I said during the GA: an excellent task for
the board.


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (Darwin)
Comment: GPGTools - http://gpgtools.org

iEYEARECAAYFAk7TlWIACgkQMkyGM64RGpGP3QCgqT0MHXqB1XsNLTEq5zHiPTSo
/CUAnR0FpleNrCBkRnDSzA0eLRzGG0bp
=ErdT
-----END PGP SIGNATURE-----

Re: Documentation problems

[Samuel Stirtzel]

2011/11/28 Tom Rini <tom.rini@gmail.com>:
[snip]
>
> The number one thing we lack today is people willing to document.
> Everyone, myself included, who has said we need X done to the public
> documentation today, has generally found a point at which they stop
> wanting to keep things up to date.  Why?  What would change that?
> Does anyone reading this know people that _like_ editing wikis?  Can
> we ask them what keeps them engaged in the process?
Hi,

The process done when documenting code (or more generally: changing
sets of information),
could be displayed as the opposition of the one documenting and the change.
For the person that documents the information the question is:
"How long does my change last until it is outdated again?"
in some cases changes last long, for others the documentation may
change every few months.



Part 1 according to the wiki:

Working with Mediawiki is not that easy (not for the editors and even
less for the administrators),
as my past experience (administrating an intranet Mediawiki with >50
users for at least 2 years) has shown me,
that updates of the infrastructure (wiki versions, extension versions)
may break content.

2011/11/28 Koen Kooi <koen@dominion.thruhere.net>:
>>Op 28-11-11 06:11, Tom Rini schreef:
>>...
>> The number one thing we lack today is people willing to document.
>
>I'd change that to "knowledgable people"

I fully agree, this is also the reason why I didn't step up and offered my help,
of course I could explain how to build an image with OE-Core (or how
to create a custom recipe for Qt etc.),
but I didn't get the experience (yet) to show users best practices, or
simply "the way to go".


By the way, some time ago I did a complete overhaul of the
wikipedia.org OE page,
as it was not informative and the first location new users would look
at is wikipedia.

It would be nice if anyone more knowledgeable could review the current version.
Version before the changes:
http://en.wikipedia.org/w/index.php?title=OpenEmbedded&oldid=414622717

Current version:
http://en.wikipedia.org/w/index.php?title=OpenEmbedded

(It is at one point already outdated since meta-texasinstruments was
renamed to meta-ti, but I think about fixing that later.)



Part 2 my humble opinion about documenting OE-Core:

FWIW, I already thought of possible ways to document OE-Core changes
(nearly automatically), before this discussion started.

After documenting parts of a software that my colleague wrote,
some c++/Qt application I documented with Doxygen, I was thinking
about the OE-Core situation.
It came to my mind that it would be great if it's possible to use
Doxygen (or maybe a Bitbake documentation module?) to document
recipes, variables and functions (e.g. custom do install).
Using a searchable HTML documentation would allow the most users would
easily to find examples of what they look for.

Also it would be possible to see every (inc / bbappend / bbclass /
dependency) file as hyperlink (to their doc) inside the documentation.
The documentation method Doxygen uses (something like /** \brief Short
summary of the following class/function/... */ in c++)
lets the user create the documentation as he edits the file and it
will remain readable inside the file too (no need for anything like a
browser or PDF viewer).
Hyperlinked dependency graphs would also be nice.


This idea of direction sounds very promising (at least to me), but
this step of course has its downsides,
afar from the concrete incompatibility of Doxygen with bash script,
the time to compose the information (of all recipes) into the
documentation would be tremendous,
it "could" take longer than building an image itself and the
documentation has to be rebuild partially after each update to stay
fresh.

Of course the scope I "suggested" was the complete documentation of OE,
so if this would only focus on variables and common functions /
leaving out per recipe informations,
then it could work out to compose the full documentation in a few minutes.

I'd like to read about your opinions / ideas regarding this.
>
> --
> Tom
>
> _______________________________________________
> Openembedded-devel mailing list
> Openembedded-devel@lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel
>



-- 
Regards
Samuel

Re: Documentation problems

[Bernhard Guillon]

On Sat, 26 Nov 2011, Tom Rini wrote:

> Hey all,
>
> 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.

Hi,
today I wanted to create a Template:We-move-to-oe-core (something like
this artikle is a stub) to mark all pages which needs a change and inform
new users about the move to oe-core. I created an account but I am unable
to edit anything. I even cannot edit my user page.

Best regards,
Bernhard

Re: Documentation problems

[Bernhard Guillon]

On Mon, 28 Nov 2011, Richard Purdie wrote:

> Rather than fork off the Yocto docs for OE's needs, it would be nice to
> see if there was a way we could share the documentation.

I like that idea + the pull based model idea from Koen. In my opinion a 
pull based model for the documentation lower the barriers to write 
documentation because nobody want to write something false.

But the project webpage should not look like a docbook page.

Best regards,
Bernhard

Re: Documentation problems

[Tom Rini]

On Mon, Nov 28, 2011 at 11:02 AM, Bernhard Guillon
<Bernhard.Guillon@opensimpad.org> wrote:
> On Mon, 28 Nov 2011, Richard Purdie wrote:
>
>> Rather than fork off the Yocto docs for OE's needs, it would be nice to
>> see if there was a way we could share the documentation.
>
> I like that idea + the pull based model idea from Koen. In my opinion a pull
> based model for the documentation lower the barriers to write documentation
> because nobody want to write something false.
>
> But the project webpage should not look like a docbook page.

In my mind, that's only half of the problem, the deep dive side of
things.  Or would that really be so few pages it doesn't matter (along
with having the full manual online) ?

-- 
Tom

Re: Documentation problems

[Frans Meulenbroeks]

2011/11/28 Bernhard Guillon <Bernhard.Guillon@opensimpad.org>

>
>
> On Mon, 28 Nov 2011, Richard Purdie wrote:
>
>  Rather than fork off the Yocto docs for OE's needs, it would be nice to
>> see if there was a way we could share the documentation.
>>
>
> I like that idea + the pull based model idea from Koen. In my opinion a
> pull based model for the documentation lower the barriers to write
> documentation because nobody want to write something false.
>

Of course I also do not want to write faulty documentation; then again I
also hate wasting my time, so I think I wouldn't even start if there was a
chance that my contribution might be rejected because the pull master does
not like my style or feels there are grammar errors or so.

(note that I am not a native english speaker so this is not too unlikely;
also if there are language errors in a contributed piece of documentation
on a wiki other people more proficient in english could correct those
easier and better than I ever can),

For me this raises the bar to contribute (not that I have contributed much
to our documentation...)

The issue with documentation
- everybody wants documentation
- hardly anyone wants to write documentation
- make it hard to write documentation and you'll end up with no
documentation.

BTW somewhere in the thread also the license issue was raised.
I'd suggest a form of creative commons with attribution clause.

Frans

Re: Documentation problems

[Khem Raj]

Hi Frans,

On Tue, Nov 29, 2011 at 12:24 AM, Frans Meulenbroeks
<fransmeulenbroeks@gmail.com> wrote:
>
> Of course I also do not want to write faulty documentation; then again I
> also hate wasting my time, so I think I wouldn't even start if there was a
> chance that my contribution might be rejected because the pull master does
> not like my style or feels there are grammar errors or so.

I consider someone reviewing my patches a good thing. I think it makes
me learn things
if there is feedback on the patches, I include the feedback and
resubmit the patch and thereby improve it


>
> (note that I am not a native english speaker so this is not too unlikely;

neither am I.

> also if there are language errors in a contributed piece of documentation
> on a wiki other people more proficient in english could correct those
> easier and better than I ever can),

right now there is no review process for wiki. So if I write a
document it does not get notified
to people and chances of someone really stumbling into this new piece
are new users who are studying
that document and I think reviewing it beforehand is a good thing
since I might have written it wrong
besides grammar errors. I think wrong documentation is worse than no
documentation.

>
> For me this raises the bar to contribute (not that I have contributed much
> to our documentation...)
>
> The issue with documentation
> - everybody wants documentation
> - hardly anyone wants to write documentation
> - make it hard to write documentation and you'll end up with no
> documentation.
>
> BTW somewhere in the thread also the license issue was raised.
> I'd suggest a form of creative commons with attribution clause.

This should be fixed yes.

Re: Documentation problems

[Frans Meulenbroeks]

2011/11/29 Khem Raj <raj.khem@gmail.com>

> Hi Frans,
>

Hi Khem, all

>
> On Tue, Nov 29, 2011 at 12:24 AM, Frans Meulenbroeks
> <fransmeulenbroeks@gmail.com> wrote:
> >
> > Of course I also do not want to write faulty documentation; then again I
> > also hate wasting my time, so I think I wouldn't even start if there was
> a
> > chance that my contribution might be rejected because the pull master
> does
> > not like my style or feels there are grammar errors or so.
>
> I consider someone reviewing my patches a good thing. I think it makes
> me learn things
> if there is feedback on the patches, I include the feedback and
> resubmit the patch and thereby improve it
>

Oh, I consider reviewing patches a good thing too. For documentation it
also depends on the process and the kind of comments.
If the person pulling the changes rejects them because (s)he finds the
grammar not ok and the review comment is "improve grammar", that is fairly
demotivating (if I knew how to do so, I would have done that upfront).
A few of such rejects will make that most people loose the interest in
submitting documentation quite quickly.
And if you have to give detailed review comments or instructions reviewing
becomes quite time consuming (actually more time consuming than actually
making the change yourself)

That is somewhat the advantage of a wiki. You can contribute to the best of
your abilities and others can extend with their knowledge, expertise and
language skills.
Then again, I understand that there is a risk that faulty information is
created (as was also expressed by Koen). However I cannot really recall big
such problems with our wiki.

There is of course another problem (which does surface every once in a
while). Sometimes people write pieces based upon outdated information. And
even if not, the information itself will become outdated.
E.g. if we deprecate PR (which is a good idea btw) this needs to be changed
in the wiki too. That is a part of the process that is not really well
developed.
outdated information is equally wrong as other faulty information.

As stated before, for most people writing documentation is not particularly
fun, so it should be made easy with few annoyances. Make it hard and you
will hardly get contributions. Turn people down a few times and they are
gone.

>
>
> >
> > (note that I am not a native english speaker so this is not too unlikely;
>
> neither am I.
>
> > also if there are language errors in a contributed piece of documentation
> > on a wiki other people more proficient in english could correct those
> > easier and better than I ever can),
>
> right now there is no review process for wiki. So if I write a
> document it does not get notified
> to people and chances of someone really stumbling into this new piece
> are new users who are studying
> that document and I think reviewing it beforehand is a good thing
> since I might have written it wrong
> besides grammar errors. I think wrong documentation is worse than no
> documentation.
>

I agree with the wrong documentation is worse than no documentation.
I'm not sure whether there are no wiki plugins to allow notification.
(and it is always possible to examine the recent changes page, but that is
not really convenient).

BTW it is always possible to lock certain pages and only allow a limited
set of users to edit those pages. I can imagine this is done wth the pages
that are considered core.

Frans

Re: Documentation problems

[Tom Rini]

On Tue, Nov 29, 2011 at 2:46 PM, Frans Meulenbroeks
<fransmeulenbroeks@gmail.com> wrote:
> 2011/11/29 Khem Raj <raj.khem@gmail.com>
>
>> Hi Frans,
>>
>
> Hi Khem, all
>
>>
>> On Tue, Nov 29, 2011 at 12:24 AM, Frans Meulenbroeks
>> <fransmeulenbroeks@gmail.com> wrote:
>> >
>> > Of course I also do not want to write faulty documentation; then again I
>> > also hate wasting my time, so I think I wouldn't even start if there was
>> a
>> > chance that my contribution might be rejected because the pull master
>> does
>> > not like my style or feels there are grammar errors or so.
>>
>> I consider someone reviewing my patches a good thing. I think it makes
>> me learn things
>> if there is feedback on the patches, I include the feedback and
>> resubmit the patch and thereby improve it
>>
>
> Oh, I consider reviewing patches a good thing too. For documentation it
> also depends on the process and the kind of comments.
> If the person pulling the changes rejects them because (s)he finds the
> grammar not ok and the review comment is "improve grammar", that is fairly
> demotivating (if I knew how to do so, I would have done that upfront).

This would be just as bad as reviewing a patch and saying only "fix
the things that are wrong".  Both are equally unacceptable, and
frankly at this point in the projects life, equally unlikely.

> A few of such rejects will make that most people loose the interest in
> submitting documentation quite quickly.
> And if you have to give detailed review comments or instructions reviewing
> becomes quite time consuming (actually more time consuming than actually
> making the change yourself)

Which probably means the commenter knows enough that they should have
made the documentation change to start with.  This is the price to pay
for not doing the edits directly.  Personally, I've been willing to
pay that cost and explaining it to someone else helps make sure I
really understand it and that the code is also really correct.

-- 
Tom

Re: Documentation problems

[Frans Meulenbroeks]

2011/11/30 Tom Rini <tom.rini@gmail.com>

> On Tue, Nov 29, 2011 at 2:46 PM, Frans Meulenbroeks
> <fransmeulenbroeks@gmail.com> wrote:
> > 2011/11/29 Khem Raj <raj.khem@gmail.com>
> >
> >> Hi Frans,
> >>
> >
> > Hi Khem, all
> >
> >>
> >> On Tue, Nov 29, 2011 at 12:24 AM, Frans Meulenbroeks
> >> <fransmeulenbroeks@gmail.com> wrote:
> >> >
> >> > Of course I also do not want to write faulty documentation; then
> again I
> >> > also hate wasting my time, so I think I wouldn't even start if there
> was
> >> a
> >> > chance that my contribution might be rejected because the pull master
> >> does
> >> > not like my style or feels there are grammar errors or so.
> >>
> >> I consider someone reviewing my patches a good thing. I think it makes
> >> me learn things
> >> if there is feedback on the patches, I include the feedback and
> >> resubmit the patch and thereby improve it
> >>
> >
> > Oh, I consider reviewing patches a good thing too. For documentation it
> > also depends on the process and the kind of comments.
> > If the person pulling the changes rejects them because (s)he finds the
> > grammar not ok and the review comment is "improve grammar", that is
> fairly
> > demotivating (if I knew how to do so, I would have done that upfront).
>
> This would be just as bad as reviewing a patch and saying only "fix
> the things that are wrong".  Both are equally unacceptable, and
> frankly at this point in the projects life, equally unlikely.
>

Hm. I'm not too sure about this. With a patch it is much easier to
distinguish between right and wrong.
With explanatory text the scale is much wider, and for text I suggest to
look at the content (which obviously should be technically ok) and perhaps
a little bit less at style and grammar (but of course it should remain
understandable).


>
> > A few of such rejects will make that most people loose the interest in
> > submitting documentation quite quickly.
> > And if you have to give detailed review comments or instructions
> reviewing
> > becomes quite time consuming (actually more time consuming than actually
> > making the change yourself)
>
> Which probably means the commenter knows enough that they should have
> made the documentation change to start with.  This is the price to pay
>

I'm not sure about this. It could well be that a reviewer comments on style
and structure, even though (s)he cannot judge the technical details (and
therefore probably could not write the piece himself).
And I feel we have some people that seem to like it to pick on other people
not following the guidelines they are not willing to document.


> for not doing the edits directly.  Personally, I've been willing to
> pay that cost and explaining it to someone else helps make sure I
> really understand it and that the code is also really correct.
>

Sure. I understand and appreciate that.
Then again for code sometimes the feedback that is given with rejected
patches is neither helpful nor stimulating.
If that happens with documentation too, soon someone will end up whining
that no one wants to contribute to the documentation.

My two cents.
Frans.

Re: 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
-- 

Re: Documentation problems

[Koen Kooi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Op 30-11-11 16:49, Rainer Koenig schreef:

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

Bugzilla started to become a liability when the OE bugzilla maintainer
didn't want patches to get reviewed on the mailing list and actually started
closing bugs as 'resolved' or 'wontfix' after people dared to post a patches
to the mailing list.
With a maintainer like that a bugzilla is useless. Thankfully Rolf
disappeared from the OE project, but the damage was already done.

As you pointed out, OE-core is tracking its bugs in the yocto bugzilla with
pretty graphs and such. Other layers may use different tools to track bugs,
it's up to the maintainers to decide what works best for them.

regards,

Koen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (Darwin)
Comment: GPGTools - http://gpgtools.org

iEYEARECAAYFAk7WYoQACgkQMkyGM64RGpECFQCfVH0oPSdE1jvPDSH9gxTBMYL9
SpUAn3jBN0WVTijtqbnOwxzeJDM6z79+
=Cg/o
-----END PGP SIGNATURE-----

Re: Documentation problems

[McClintock Matthew-B29882]

On Wed, Nov 30, 2011 at 9:49 AM, Rainer Koenig
<Rainer.Koenig@ts.fujitsu.com> wrote:
> 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.

Just a small rant here.

I won't use the Wiki because I don't know what is out of date or not.
We need documentation in the git repo it's documenting. That way we
know the documentation was valid when it was committed and we can
verify such things.

The wiki/webpage should just reference stuff in the GIT repo.

-M

Re: Documentation problems

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 5316 bytes --]

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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: Documentation problems

[Bill Traynor]

On Mon, Nov 28, 2011 at 12:44 PM, Bernhard Guillon <
Bernhard.Guillon@opensimpad.org> wrote:

>
>
> On Sat, 26 Nov 2011, Tom Rini wrote:
>
>  Hey all,
>>
>> 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.
>>
>
> Hi,
> today I wanted to create a Template:We-move-to-oe-core (something like
> this artikle is a stub) to mark all pages which needs a change and inform
> new users about the move to oe-core. I created an account but I am unable
> to edit anything. I even cannot edit my user page.
>

This is fixed now.

I've just implemented  Email Confirmation for New Users to the wiki with
auto-promotion to the 'User' group to allow for editing.  I also switched
the Captcha from recaptcha to QuestyCaptcha with a simple question about
Linux that's easily google-able.  This scheme has worked well for a number
of months on elinux.org, so it seemed prudent to try it here as well.

More wiki improvements to come.

Thanks
Bill


> Best regards,
> Bernhard
>
>
> ______________________________**_________________
> Openembedded-devel mailing list
> Openembedded-devel@lists.**openembedded.org<Openembedded-devel@lists.openembedded.org>
> http://lists.linuxtogo.org/**cgi-bin/mailman/listinfo/**openembedded-devel<http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel>
>



-- 
Bill Traynor
Technical Writer & Community Manager of Meld.org
MontaVista Software, LLC
2929 Patrick Henry Drive
Santa Clara, CA 95054

Re: Documentation problems

[Khem Raj]

On (07/12/11 00:01), Bill Traynor wrote:
> > Hi,
> > today I wanted to create a Template:We-move-to-oe-core (something like
> > this artikle is a stub) to mark all pages which needs a change and inform
> > new users about the move to oe-core. I created an account but I am unable
> > to edit anything. I even cannot edit my user page.
> >
> 
> This is fixed now.
> 
> I've just implemented  Email Confirmation for New Users to the wiki with
> auto-promotion to the 'User' group to allow for editing.  I also switched
> the Captcha from recaptcha to QuestyCaptcha with a simple question about
> Linux that's easily google-able.  This scheme has worked well for a number
> of months on elinux.org, so it seemed prudent to try it here as well.
> 

Thanks Bill this should solve our spammy problems

> More wiki improvements to come.

looking forward to it.

Re: Documentation problems

[Andreas Schwab]

Bruce Korb <bruce.korb@gmail.com> writes:

> I'm trying to figure out what a ``tree-ish''.
> I cannot seem to use many of the commands until I know.
>
> <tree-ish>
>     Indicates a tree, commit or tag object name. A command that takes a
>     <tree-ish> argument ultimately wants to operate on a <tree> object
>     but automatically dereferences <commit> and <tag> objects that point at a <tree>.
>
> I need a translation.  :(  Thank you.  Regards, Bruce

See gitglossary(7).

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Documentation problems

[Matthieu Moy]

Bruce Korb <bruce.korb@gmail.com> writes:

> Since I haven't created any any branches (to my knowledge), it seems
> that "master" is the magic branch name.

I wouldn't say "magic", but surely the default ;-).

> My goal was just to get a list of managed files.

Just cd /where/your/repo/is
git ls-files

> Is "master" going to remain my "HEAD" now?

Yes.

>> git-ls-tree is the old way to
>> refer to the command name. Normally, any reference to dashed names
>> should have been removed from the documentation by now (so most likely
>> you see it in your distro because it's an old enough version,
>> otherwise, it's a bug in the doc).
>
> $ git --version
> git version 1.6.0.2
>
> I guess the man pages and installation were out of sync for that release.

Well, actually, a few more instances of dashed commands were removed
more recently. That said, to get the doc for "git foo", you still have
to type "man git-foo" (or git foo --help indeed), but that's because
"man git foo" means something different to man.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Documentation problems

[Bruce Korb]

Hi Matthieu,
>> I'm trying to figure out what a ``tree-ish''.

>> I need a translation.  :(  Thank you.  Regards, Bruce
> 
> tree = directory (with its content).
> 
> For example, the last commit in the current branch is a Git object of
> type "commit", which contains mostly a log message, a few headers, and
> a pointer to the tree object corresponding to the content of the
> directory in which you made the commit (modulo what you excluded from
> the commit of course). Therefore, the name of this commit, although
> not really a tree, is a tree-ish in that it talks about one and only
> one tree. You could name it HEAD, a sha1sum (like
> 5a2abc12d64a5e00daa6aebbb673715f365a564a), the name of the branch
> (like "master"), ...

Since I haven't created any any branches (to my knowledge), it seems
that "master" is the magic branch name.  My goal was just to get a
list of managed files.  Is "master" going to remain my "HEAD" now?
(Assuming I don't do something to make a new branch.  One branch
is enough for my little one person project....)

> Just type "git ls-tree --name-only".
Ah.  Thank you.
> git-ls-tree is the old way to
> refer to the command name. Normally, any reference to dashed names
> should have been removed from the documentation by now (so most likely
> you see it in your distro because it's an old enough version,
> otherwise, it's a bug in the doc).

$ git --version
git version 1.6.0.2

I guess the man pages and installation were out of sync for that release.

Thank you for the quick reply!  Regards, Bruce

Re: Documentation problems

[Matthieu Moy]

Bruce Korb <bruce.korb@gmail.com> writes:

> Hi,
>
> I'm trying to figure out what a ``tree-ish''.
> I cannot seem to use many of the commands until I know.
>
> <tree-ish>
>     Indicates a tree, commit or tag object name. A command that takes a
>     <tree-ish> argument ultimately wants to operate on a <tree> object
>     but automatically dereferences <commit> and <tag> objects that point at a <tree>.
>
> I need a translation.  :(  Thank you.  Regards, Bruce

tree = directory (with its content).

For example, the last commit in the current branch is a Git object of
type "commit", which contains mostly a log message, a few headers, and
a pointer to the tree object corresponding to the content of the
directory in which you made the commit (modulo what you excluded from
the commit of course). Therefore, the name of this commit, although
not really a tree, is a tree-ish in that it talks about one and only
one tree. You could name it HEAD, a sha1sum (like
5a2abc12d64a5e00daa6aebbb673715f365a564a), the name of the branch
(like "master"), ...

> P.S. I have a SuSE installation with everything relating to GIT installed.
> The man pages reference commands like, "git-ls-tree --name-only" except
> that there isn't any such command.  Unless you reverse engineer the
> implementation of "git", discover the /usr/lib/git directory and add it
> to your path.  That hassle is rather inconvenient.  More hints about
> where the git commands get squirreled away would be useful.  Thank
> you.

Just type "git ls-tree --name-only". git-ls-tree is the old way to
refer to the command name. Normally, any reference to dashed names
should have been removed from the documentation by now (so most likely
you see it in your distro because it's an old enough version,
otherwise, it's a bug in the doc).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Documentation problems

[Bruce Korb]

Hi,

I'm trying to figure out what a ``tree-ish''.
I cannot seem to use many of the commands until I know.

<tree-ish>
    Indicates a tree, commit or tag object name. A command that takes a
    <tree-ish> argument ultimately wants to operate on a <tree> object
    but automatically dereferences <commit> and <tag> objects that point at a <tree>.

I need a translation.  :(  Thank you.  Regards, Bruce

P.S. I have a SuSE installation with everything relating to GIT installed.
The man pages reference commands like, "git-ls-tree --name-only" except
that there isn't any such command.  Unless you reverse engineer the
implementation of "git", discover the /usr/lib/git directory and add it
to your path.  That hassle is rather inconvenient.  More hints about
where the git commands get squirreled away would be useful.  Thank you.