Re: Documentation problems

[Richard Purdie <richard.purdie@linuxfoundation.org>]

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