barebox Documentation

[Sascha Hauer]

Hi,

As we all know the barebox documentation sucks. We @Pengutronix will
have our internal techweek next month. One of the goals will be to
improve the documentation situation for barebox.

What are your opinions in which form the documentation should be?

We currently have plain text files under Documentation/, a wiki on
http://wiki.barebox.org/doku.php and doxygen. None of the documentation
sets is complete and all are outdated.

Some pros and cons of the existing approaches are:

Plain text files
+ Easy to write
+ no extra step to generate docs, wysiwyg ;)
- no links
- no pictures

Wiki
- not contained in the repository, so may be out of sync
+ links
+ nice markup language

doxygen
+ contained in the repository
+ easy html doc generation
+ links
- extra step to generate the docs

So what are your opinions, what should be updated and what should be
dropped? Kconfig has an extra role here. It cannot provide a full
documentation, but should be updated and maintained.

Sascha

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |