[oe] [RFC] Documentation problems and future plans

[Chris Larson]

On Sun, Nov 27, 2011 at 2:58 AM, Paul Menzel
<paulepanter at 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