[oe] Documentation problems

[Samuel Stirtzel]

2011/11/28 Tom Rini <tom.rini at 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 at 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 at lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel
>



-- 
Regards
Samuel