[Nix-dev] Fwd: Wiki is dead

[Rok Garbas]

Hi Eelco,

>> I've given this a try [1] for the zero-build-failures entry and my experience so
>> far was:
>>
>> 1/ How do I actually build docbook?
>>   => copy doc/default.nix and adjust
>> 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think).
>>   => Wait 2h.
>> 3/ GHC build fails [2]
>> 4/ We're not using standard docbook but preprocess with XSLT so references on
>> the internet don't actually work.
>
> This speaks in favor of keeping *all* docs in Docbook format so we don't need
> conversion tools like Pandoc. Then the manual generation only depends on
> xsltproc  and docbook-xsl. This is pretty much a hard requirement for the NixOS
> manual because I don't think it's a good idea for the core system to pull in Pandoc.
>
> In fact, I think having multiple formats is not a good idea in general, because
> it makes it hard to restructure the manual (e.g., you can't just move a manual
> fragment between different sections if they're written in different formats).
> And it requires contributors to learn the idiosyncrasies of multiple formats.
>

adding another tool to the build chain is something nobody wants. we
all agree on that.

on the other hand we _must_ look at why contributors are using other
tools. docbook is
just something that is not known by majority of our community.
markdown or such would
be much more generally accepted markup, which wouldn't require majority of our
community to learn in order to contribute to documentation.

current situation is as it is and while we migrate wiki and refactor
the manual into
something also more suitable for newcomers, we should not change the tools.

but as we will move forward with the project i urge you to consider
some other markup for
documentation which have bigger community adoption. i will learn
whatever is decided
(even docbook), but i will be very hard to convince others to do as
well. i would not like to
rush in any decision, but please put some thoughts on this.

once you said "until i'm mostly the only one writing documentation we
will not change
from docbook". i hope that in next months i will be able to show you
that documentation
is being written/extended by many and many more would contribute if
docbook wouldn't be
an obstacle.

my only goal is to have as good documentation as possible. i'm sure
everybody feels the
same. i think we can also agree that the only way to keep
documentation of a community
project like this is that everybody contributes. being docbook or any
other markup please
consider giving a hand.

thank you!


-- 
Rok Garbas - https://www.garbas.si