Re: [request for review] Port of s6 documentation to mdoc(7)

["Laurent Bercot" <ska-supervision@skarnet.org>]

  For the people who are not on #s6 and have missed the countless
resurgences of this discussion, here is my position regarding
documentation formats. I hope that by the end of this mail things are
quite clear for everyone and I won't need to talk about this again, 
ever.

  - Doc formats seem to be the #1 thing that's on people's minds, because
it's a subject that keeps showing up *all the time*. To me, this is
unfortunate; I wish people would spend more time on technical design
discussions and be more curious about the internals of my software, and
a bit less on surrounding things like how the documentation is written.

(Yes, Guillermo, I will answer your mail. You should really join #s6
if possible, because I talked about the plans for s6-rc there; and I
would also very much enjoy your precious willingness to talk software
details.)

  - Everyone always has a lot of ideas on how things should go and what
I should do.

  - Unfortunately, I have *zero* interest in doing those para-software
things. I am interested in writing software that does stuff, not in
spending my time learning a new rich text format and rewriting
documentation. The time I am willing to devote to free software is best
employed actually writing code, not doing things I hate. Writing doc is
enough of a chore as is; it needs to be as easy as possible for me,
without any additional hurdle getting in the way.

  - And that should really be no big deal. There is a whole community
interested in s6 documentation, and making man pages, etc., and who
always sounds very enthusiastic. So, it should be easy to find people
who are willing to invest some time and do the thing the community 
wants,
right?

  - For some reason, it turns out that it's not that easy. Somehow, the
people who always have a lot of ideas are nowhere to be found when I
try to delegate the work.

  - This pattern has been replicating for a long while now, and it has
made me quite jaded, to the point that I now lose patience very quickly
whenever documentation formats are mentioned, and I sometimes cannot 
help
answering with a jab at the end.

  - Alexis' contribution is, literally, one-of-a-kind: someone wanted a
thing to be done *and did it themself*. That is something I respect,
something that has a lot of value to me, and I want to make that work
useful.

  - Yes, it would be better to have One Single Source Of Truth, rather
than duplication of information. I totally agree on the principle.
However, as of now, the limiting factor is *not* the consistency checks
between two sets of documentation. It is the amount of human time that
is voluntarily dedicated to the task of providing said documentation.
Talking about the N+1 ways of getting One Source Of Truth and generating
several backend documentation formats accomplishes nothing. I know
about DocBook; by now, I know about every single freaking documentation
format and toolchain in existence, and about every single possible
workflow I could use. That does not change the fact that it would be
more burden placed on me, that I have no intention of taking.

- scdoc is, in a way, an exception: ddv and I had a long talk, the scdoc
format is simple enough, the toolchain is good quality, I have no
objection to writing new documentation in scdoc. (Emphasis on new;
existing doc will have to be converted by someone else than me. Or I
could be paid to do it.) The problem is that at the moment it does not
produce HTML, and post- processing the roff output produces horrible,
ugly HTML, so it's not an acceptable solution. So, for now, scdoc is not
usable for the purpose of a multi-format s6 documentation. But if it
grows a decent HTML engine, it will be.

  - What we have with Alexis' work is two sources of truth, that will
have to be kept in sync, but that's work they're willing to do - it's
the first thing I asked - and that will make the community happy, that
will improve on the current situation. If maintaining the set of man
pages in sync with the official documentation reveals itself to be
unsustainable, *then* will be the time to do something about it.

  - Unless, of course, someone comes up with the perfect solution (adding
a DocBook dependency is not a perfect solution, and neither is
generating HTML from mandoc), in which case, obviously, they would have
the time and willingness to do all the necessary work themself, and in
doing so, actually meaningfully contribute to the community instead of
only adding their drop to the useless sea of It's Easy You Just Have To
Do This, Just Saying In Case You Had Not Considered.

--
  Laurent