mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Sascha Hauer <s.hauer@pengutronix.de>
To: barebox@lists.infradead.org
Subject: barebox Documentation
Date: Tue, 13 May 2014 15:42:28 +0200	[thread overview]
Message-ID: <20140513134228.GQ5858@pengutronix.de> (raw)

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

             reply	other threads:[~2014-05-13 13:42 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-05-13 13:42 Sascha Hauer [this message]
2014-05-13 13:50 ` Robert P. J. Day
2014-05-15 12:29   ` Sascha Hauer
2014-05-13 13:55 ` Jean-Christophe PLAGNIOL-VILLARD
2014-05-13 14:01 ` Holger Schurig
2014-05-13 14:18   ` Sascha Hauer
2014-05-13 14:32     ` Holger Schurig
2014-05-13 17:45     ` Baruch Siach
2014-05-13 15:44 ` Antony Pavlov

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20140513134228.GQ5858@pengutronix.de \
    --to=s.hauer@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox