barebox Documentation

[Jean-Christophe PLAGNIOL-VILLARD]

On 15:42 Tue 13 May     , Sascha Hauer wrote:
> 
> 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
soso
> 
> Wiki
> - not contained in the repository, so may be out of sync
> + links
> + nice markup language
useless if no internet
> 
> doxygen
> + contained in the repository
> + easy html doc generation
> + links
> - extra step to generate the docs
why not use the same as the kernel simply

> 
> 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 |
> 
> _______________________________________________
> barebox mailing list
> barebox at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox