barebox Documentation

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 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Robert P. J. Day]

On Tue, 13 May 2014, 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.

  as i want to introduce barebox into future embedded linux classes of
mine, i have a vested interest in making sure the documentation is
good. so while others argue about the proper format, i'll be happy to
put my editing talents to work and do a lot of proofreading.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: 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@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Holger Schurig]

If wiki and doxygen are not updated, than this is a sign that they
should probably be outphased.

Instead, I'd prefer to have text files in the Documentation/ tree. So
changes to them pass the normal review process.

> Plain text files
> - no links
> - no pictures

If we use some special format for them, e.g. Markdown or *.rst, then
the files can still converted to HTML, and links and images could
still be possible. That would mean that wiki.barebox.org probably goes
away, but that (part) of www.barebox.org is generated from the
*.rst/Markdown files.

I personally would rather change local text files than online some
wiki. Locally, I can use grep, Emacs, python-scripts and so on. On the
wiki, I can just use keyboard and mouse ...

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Sascha Hauer]

On Tue, May 13, 2014 at 04:01:07PM +0200, Holger Schurig wrote:
> If wiki and doxygen are not updated, than this is a sign that they
> should probably be outphased.
> 
> Instead, I'd prefer to have text files in the Documentation/ tree. So
> changes to them pass the normal review process.

+1

> 
> > Plain text files
> > - no links
> > - no pictures
> 
> If we use some special format for them, e.g. Markdown or *.rst, then
> the files can still converted to HTML, and links and images could
> still be possible. That would mean that wiki.barebox.org probably goes
> away, but that (part) of www.barebox.org is generated from the
> *.rst/Markdown files.

This sounds like the best of two worlds. Do you know an example of a
project with markdown/rst documentation?

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@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Holger Schurig]

Many, many projects on github uses *.rst, e.g.
https://github.com/walac/pyusb, thougth usually only one-page.

The flask project (a web framework for python) however has a nice
website http://flask.pocoo.org/ that is generated from many text file,
e.g. https://github.com/mitsuhiko/flask/tree/master/docs/tutorial

And I did myself once converted a bunch of markdown files into HTML
and used "sitecopy" to send them over to a sub-part of a website.

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Antony Pavlov]

On Tue, 13 May 2014 15:42:28 +0200
Sascha Hauer <s.hauer@pengutronix.de> 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
> 
> Wiki
> - not contained in the repository, so may be out of sync

http://en.wikipedia.org/wiki/Gitit_%28software%29 ?

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

- not trivail board documentation adding (e.g. there is Documentation/boards.dox, and
there is arch/arm/mach-omap/arch-omap.dox too)

-- 
Best regards,
  Antony Pavlov

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Baruch Siach]

Hi Sascha,

On Tue, May 13, 2014 at 04:18:35PM +0200, Sascha Hauer wrote:
> On Tue, May 13, 2014 at 04:01:07PM +0200, Holger Schurig wrote:
> > If wiki and doxygen are not updated, than this is a sign that they
> > should probably be outphased.
> > 
> > Instead, I'd prefer to have text files in the Documentation/ tree. So
> > changes to them pass the normal review process.
> 
> +1
> 
> > > Plain text files
> > > - no links
> > > - no pictures
> > 
> > If we use some special format for them, e.g. Markdown or *.rst, then
> > the files can still converted to HTML, and links and images could
> > still be possible. That would mean that wiki.barebox.org probably goes
> > away, but that (part) of www.barebox.org is generated from the
> > *.rst/Markdown files.
> 
> This sounds like the best of two worlds. Do you know an example of a
> project with markdown/rst documentation?

Buildroot generates its manual from in-tree AsciiDoc formatted files under 
docs/manual/. PDF, HTML, epub, and text output formats are supported. See 
http://buildroot.net/docs.html for the generated result. See 
docs/manual/manual.mk (included from the top level Makefile) for the build 
recipes.

baruch

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch@tkos.co.il - tel: +972.2.679.5364, http://www.tkos.co.il -

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: barebox Documentation

[Sascha Hauer]

Hi Robert,

On Tue, May 13, 2014 at 09:50:03AM -0400, Robert P. J. Day wrote:
> On Tue, 13 May 2014, 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.
> 
>   as i want to introduce barebox into future embedded linux classes of
> mine, i have a vested interest in making sure the documentation is
> good. so while others argue about the proper format, i'll be happy to
> put my editing talents to work and do a lot of proofreading.

Thanks for the offer. I'll let you know when there's something to
proofread.

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@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox