Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

On Fri, Feb 24, 2017 at 9:11 AM, Douglas Stanley <doug at dstan.net> wrote:

> Hi, mostly long time lurker here.
>
> I feel like there's an argument about getting new documentation written by
> SME's and that markdown is easier to get into.
>
> I have to agree that markdown is really pretty easy to pick up and can be
> written on a headless server over ssh with vim and visually look good as
> you're writing it.
>
> I also get that there are style guidelines to adhere to and that the
> docbook XML is best suited to do just that.
>
> What if documentation could be written by people who know the content in
> the format their comfortable with, say markdown or reStructuredText, then
> use something like pandoc to convert their work into the appropriate
> docbook XML? I know pandoc has a way to use templates if you want to
> customize the output too. So if your docbook is not vanilla, a template can
> be created to convert things into your specific docbook flavor.
>
> Create sort of a pipeline system. Have a git repo where people can submit
> their markdown and then it gets massaged into appropriate docbook XML by
> those who are the docbook experts.
>
> I know it's not quite ideal, but both sides of the argument can get what
> they want. Just a thought I had.
>
>
Hi Doug, thanks for speaking out, and nice to meet you.

Your idea is interesting. The main problem, though, is the lack of human
resources required. There are only a couple of people who inspect all
incoming contributions, which are, like I said before, primarily reviews
and corrections. So an increase in actual new content in addition to an
extra step of converting to XML is unimaginable.

Peter