rfc64_notes_1.txt

Domen

do we want to have a poll?

or rather a survey?

is weight of all people the same?

should the poll require some investment (given that contributing to docs isn't trivial)


- which of these formats are you familiar with (that you have written documentation in)

- what's your favorite documentation format to write in? 

- have you written documentation for nix yet?

- which of these would you like nix community to us

- were you previously discrouaged to write documentation?

why for each of these questiosn?


date until when all proposals should be handled in

scope of the rfc should be the contents of the proposal, then we can create documentation team


is it a good idea to have a single documentation format? yes

should we edit the format before its converted?

well written documentation?


alysis will do survey

end of June for proposals

survey starts at the begining of June

2 weeks for survey

-----

@jtojnar

assym: missing demos (required for inclusions)
transfer all comments into rfc body
qyliss: do we need the poll?
domen: throwing poll is cheap
qyliss: uvědomění
what do we expect from the poll?
assymetric: popularity contest, let's take it as that, gauging polpularity is useful, make the results one of the factors
domen: multiple questions
qyliss: survey sounds nicer -- looking to collect data, but not a thing to make a decision
silvan: I do not like participating in surveys, too much effort
polls are easier, maybe it is not a good thing though
qyliss: agrees, not all opinions are valuable (people who will never contribue)
willing to spend 5 mins is reasonable cost, 10 minuts reasonable
poll easy to get passionate about
jtojnar: polls instant gratification
silvan: ok, survey, what to ask?
qyliss: familiar? like to use? favourite tech docs, look at that
used in the past but not happy?
assym: check used, check bad fit, check good fit, have you written nixpkgs docs
silvan: tried before but was discouraged, why? xml, too big…
qyliss: ask why?
silvan: supported?
qyliss: optional

## format comparisons
assym: should we even include the format in the survey?
silvan: ask if they would be willing to learn

domen: poll before or after the decision
consensus: before

include docbook
excluding them formats from a survey?
silvan: if noone even steps up to demo, how would we migrate to it?
assym: deadline
domen: avoid too much choice

domen: decide on the date?
will the rfc be binding? core members might not like it?

jtojnar: still in favour of docbook
we can learn from the RFC how to improve the docbook toolchain

silvan: moving docs closer to documented
domen: we should not expand the scope

silvan: scope → nixos + nixpkgs
assym: officially sanctioning multiple formats?
qyliss: should whe have just one format?
agreed on having a single format as the output of rfc
silvan: <o-o-s> remove outdated docs to make conversion easier
qyliss: cleanup sprint for 20.09 </o-o-s>

assymetric: missing requirements
translations
domen: we hardly have English docs contributors, we should not make it a hard requirements
qyliss: guix has internationalized docs
conclusion: add as nice to have

jtojnar: easiness is relative
infinisil: I just want to write text
qyliss: proper structure is important, authoring experience is similar
adoc + rst good, md worse
silvan: question of tooling, more important

assymetric: callouts? nice to have?
silval: never seen them anywhere else
qyliss: okay to lose them but a shame, some weight

jtojnar: option links withing code blocks?

crossreferences
domen: asciidoc has external plugins, rest native

infinisil: <o-o-s> lib docs </o-o-s>

domen: we will have to create our own markdown flavour
assym: if someone presents a tool, we could use it

olinks as requirements?

what's next?
prepare survey: qyliss
pick survey software
decide on deadline for proposals: End of June
start the survey

decision for the next release

next meeting in a month

----

asymmetric

* Meeting notes
** Actionable points
- moving (uncontroversial) information from the comments to the RFC
- survey instead of poll
- move translations to nice to have
** Poll
- easy to sybil
- could be a way to gauge popularity
  - let's call it a survey then
** Survey
*** Questions
- familiarity with each format
- which would you like
- have you written documentation
- have you ever been prevented by something when you wanted to?
*** Would happen before RFC is closed
*** Only include formats that have a demo
*** Create a deadline by which demos have to be implemented
** One format to rule them all