<jtojnar>
I think it would be best to revert the ad hoc fixes in staging-next and merge staging again
drakonis has joined #nixos-dev
andi- has quit [Ping timeout: 248 seconds]
andi- has joined #nixos-dev
init_6 has joined #nixos-dev
ajs124 has quit [Quit: Gateway shutdown]
drakonis has quit [Quit: Leaving]
orivej has joined #nixos-dev
init_6 has quit []
init_6 has joined #nixos-dev
orivej has quit [Ping timeout: 240 seconds]
orivej has joined #nixos-dev
orivej has quit [Ping timeout: 258 seconds]
init_6 has quit []
orivej has joined #nixos-dev
orivej has quit [Ping timeout: 268 seconds]
FRidh has joined #nixos-dev
<domenkozar[m]>
this debate will never end as long as it's around the format
<domenkozar[m]>
but missing the rest of the picture which is the non-bikeshedding part
<domenkozar[m]>
tooling infrastructure and maintenance is far more important and time consuming for us than which 4 chars you have to use to achieve bold
lopsided98 has quit [Quit: No Ping reply in 180 seconds.]
<domenkozar[m]>
or if the format can draw fractals
lopsided98 has joined #nixos-dev
<domenkozar[m]>
but most important of it all is that the lack of decision is costing us much more than a difference between the two solutions we might pick from
<MichaelRaskin>
Documentation is write-only: nobody who can write a good description of X needs it. This _is_ the everyday cost. And the tooling will end up being set up in a single sprint never to be touched again
<domenkozar[m]>
> And the tooling will end up being set up in a single sprint never to be touched again
<{^_^}>
error: syntax error, unexpected IN, expecting ')', at (string):272:42
<domenkozar[m]>
that's how microsoft sells their software and we all know it's a lie :D
<domenkozar[m]>
more concretely: try to estimate how much hours we've put into manual tooling
<MichaelRaskin>
Mostly because there is that registry thing that cannot decide if it is an FS, a database or what, but definitely knows it is not versionable
<MichaelRaskin>
Less than into hunting the Docbook section mismatch?
<domenkozar[m]>
writing overhead between formats is small
<domenkozar[m]>
most of it is congitive overhead that's hard to argue about since people have different mileage
<domenkozar[m]>
on the other hand, features are important
<domenkozar[m]>
like importing a file in markdown to multiple locations is tricky
<domenkozar[m]>
while most proper documentation tools have it
<domenkozar[m]>
the way I look at this works for all communities: if I wanted to do X in Nix, I'd ask a few prominent folks at nixcon and have a pretty good benchmark that either the answers are similar and there's a convergence and good confidence the opinion is good
<domenkozar[m]>
that's the sole reason I went to writethedocs, community is pretty set that docbook is dead and markdown is insufficient
<domenkozar[m]>
what I'm afarid is that we have too many smart folks that are willing to fight against the wind
<domenkozar[m]>
which is great, but I think documentation is the wrong battle :)
justanotheruser has quit [Ping timeout: 265 seconds]
<MichaelRaskin>
I wonder if setting up pandoc for any-to-docbook and committing both true source and docbok is a good idea
<infinisil>
domenkozar[m]: Nice, how did you generate that?
<domenkozar[m]>
pandoc :)
<domenkozar[m]>
in 2014
<infinisil>
Okay so I am convinced of all three, markdown, asciidoc and rst now, I'd be happy with any of them
<domenkozar[m]>
:D
<domenkozar[m]>
I think we mainly just need to make a decision.
<infinisil>
Ohh discourse has a poll feature
<infinisil>
We could use that to decide (while presenting all the positives and negatives of each format along them)
<adisbladis>
Ugh... I don't think voting is the best approach here
<adisbladis>
Too much bike shedding potential
<adisbladis>
Just present one implementation that you prefer
<infinisil>
What is everybody complaining about bikeshedding all the time
<infinisil>
It's just a discussion
<adisbladis>
I've seen this discussion many times before and it seems that it's always the same
<infinisil>
If we're going to stick to some format for the next 10 years it better have some good discussions and arguments
<domenkozar[m]>
yes - because there's a lack of decision, all arguments have been put together
<domenkozar[m]>
we're like a smoker talking to stop smoking all the time :D
<domenkozar[m]>
all there's missing is a decision how do we decide, that's the deadlock
<infinisil>
Okay so how about this: I make a poll where I present all mentioned options along with their advantages/disadvantages from *other* threads. I point out that if they want to bring up more arguments they should discuss them elsewhere
<infinisil>
Though then I'd have to update the poll somehow
<gchristensen>
we need to get more facts not just vote
<gchristensen>
like closure size
<domenkozar[m]>
closure size will be smaller since there won't be 3 formats
<infinisil>
Scratch that! I'll just make a draft poll, ask some people that have interest to review that draft, *then* I post it to discourse
<infinisil>
And we decide that whatever the result of that draft is should be used, no discussions anymore
<infinisil>
s/draft/poll
<infinisil>
It's going to be a multiple-choice poll, so we'll get a result of "how many people approve of each format". Then if it turns out that the top-voted one can't be used, e.g. because of closure size, then we'll use the second choice
<infinisil>
gchristensen: ^
<domenkozar[m]>
gchristensen: runtime or build closure?
<domenkozar[m]>
currently pandoc is 2.4GB
<domenkozar[m]>
so that's easy to beat :D
<infinisil>
build closure
<domenkozar[m]>
antora is 250MB
<infinisil>
The argument was that asciidoctor has ~1GB
<infinisil>
But in comparison to pandoc that's not a lot now
<domenkozar[m]>
antora doesn't
<domenkozar[m]>
(it has asciidoctor compiled to JS)
<domenkozar[m]>
so pretty sure we can get below 200M
<infinisil>
Nice, so let's not worry about that
<domenkozar[m]>
the only thing I'd worry is why we didn't make a decision in last 5 years
<domenkozar[m]>
and how much longer it will take :)
<infinisil>
I want this decided within 1 month!
<infinisil>
I'll first assemble a list of core people to be included in the poll-reviewing, we'll have the poll in say 2 weeks then
<infinisil>
Closing the poll at 2019-02-01
<domenkozar[m]>
might be better to write an RFC
justanotheruser has quit [Ping timeout: 252 seconds]
<infinisil>
I don't want to use up the little motivation I have for writing an RFC, only for it to be stuck for half a year or longer (or not at all, who knows)
<infinisil>
And this is only a one-time thing anyways
<domenkozar[m]>
I think RFC will have a better outcome than a vote
<domenkozar[m]>
it has more trust in the community
<gchristensen>
and forces through some of the critical thinking which I think will be necessary for any later steps to be effective
<infinisil>
Wait, you mean an RFC to decide on the format?
<domenkozar[m]>
No, a concrete proposal
<infinisil>
If somebody wants to do an RFC on that, feel free, but I won't do it
<domenkozar[m]>
infinisil: what if you write the facts about formats and that's part of the RFC?
<domenkozar[m]>
in Motivation section
<domenkozar[m]>
there would still be voting by shepherds
<domenkozar[m]>
with the same content more or less
<infinisil>
That doesn't sound too bad
<domenkozar[m]>
yay :)
<infinisil>
But then it we'll never finish in a month
<infinisil>
s/it//
<infinisil>
More like half a year
<domenkozar[m]>
can still finish in a month, but it will be merged in 6 months
<infinisil>
I mean to finish the final vote on the format
<domenkozar[m]>
I'm OK as long as we know there's going to be a decision
<domenkozar[m]>
I'd love a shorter path, but I don't see it
<infinisil>
I guess with an RFC we have the official OK that the result has to be accepted
<domenkozar[m]>
yes
<infinisil>
Alright I might write an RFC for that
<infinisil>
But what format should I write it in?!
<gchristensen>
runes
<infinisil>
xD
<MichaelRaskin>
Markdown, to get that extra emotion into your arguments against it.
<infinisil>
Very good
<domenkozar[m]>
:D
<infinisil>
Candidates will be: markdown, rst, asciidoc, docbook and orgmode (just because it's been mentioned and there's a PR for it), anything else?
<gchristensen>
I don't think orgmode has a chance of being a serious candidate
<infinisil>
Yeah probably, might not be worth putting it in even. Any other formats though?
<gchristensen>
what, no runes? :)
<infinisil>
Um, sure!
justanotheruser has joined #nixos-dev
<Profpatsch>
that one structured documentation language I’ve been meaning to write!