What's the missing is a culture in which consumers put questions directly
into documentation for answering by the next person who reads it and knows
the answer.
Note that it's not good enough to implement an append-only authorship for
Q&As, the question and the answer need to feed back into a re-wording of
the original documentation.
Using plain text sources for documentation such as asciidoc within a simple
editing suite (github is just about good enough) lowers the barriers.
On 16 April 2015 at 09:28, Simon Lundström simlu@su.se wrote:
On Tue, 2015-04-14 at 09:15:25 +0100, James Green wrote:
[…]
It was never intended to document software use, which is what support
lists
like this end up being used for. If I want to know how to do something or
what I might be doing wrong I'd prefer to place the question in precisely
the correct way and have it answered as part of the ongoing documentation
effort for others to read. This ongoing refinement of knowledge is what
ultimately drives forward adoption. A mailing list of far too fragmented
to
achieve this - wrong tool for the job.
I don't think forums (and thus Discourse) is the solution for this
either. StackOverflow et.al. is OK but it's not really a good medium
IMO. The project should take ownership of their docs and discussions so
they can be correct and not just guessing.
Official documentation which can be contributed to (via PRs is OK for
me) by the community is a better solution IMO. This demands a clear
structure from the project where things are supposed to be (i.e.
"reference documentation for plugin X" vs. "this is how I solved X" vs.
"What's best practice for LS/ES/plugin X") so we don't get yet another
messy place where noone can find anything and it's an exhausting and
daunting experience to find (or add) anything.
However many times have we asked Google a question and come back with a
mailing list post four-five years old which appears to be on the money,
yet
the answer no longer appears to apply?
I agree and even worse is when noone has answered it all and it's the
only hit. Or my favourite: when your (generic and/or exact) search query
yields no hits at all.
BR,
Simon
--
Remember: if a new user has a bad time, it's a bug in logstash.
What's the missing is a culture in which consumers put questions directly
into documentation for answering by the next person who reads it and knows
the answer.
Note that it's not good enough to implement an append-only authorship for
Q&As, the question and the answer need to feed back into a re-wording of
the original documentation.
Using plain text sources for documentation such as asciidoc within a
simple editing suite (github is just about good enough) lowers the barriers.
On 16 April 2015 at 09:28, Simon Lundström simlu@su.se wrote:
On Tue, 2015-04-14 at 09:15:25 +0100, James Green wrote:
[…]
It was never intended to document software use, which is what support
lists
like this end up being used for. If I want to know how to do something
or
what I might be doing wrong I'd prefer to place the question in
precisely
the correct way and have it answered as part of the ongoing
documentation
effort for others to read. This ongoing refinement of knowledge is what
ultimately drives forward adoption. A mailing list of far too
fragmented to
achieve this - wrong tool for the job.
I don't think forums (and thus Discourse) is the solution for this
either. StackOverflow et.al. is OK but it's not really a good medium
IMO. The project should take ownership of their docs and discussions so
they can be correct and not just guessing.
Official documentation which can be contributed to (via PRs is OK for
me) by the community is a better solution IMO. This demands a clear
structure from the project where things are supposed to be (i.e.
"reference documentation for plugin X" vs. "this is how I solved X" vs.
"What's best practice for LS/ES/plugin X") so we don't get yet another
messy place where noone can find anything and it's an exhausting and
daunting experience to find (or add) anything.
However many times have we asked Google a question and come back with a
mailing list post four-five years old which appears to be on the money,
yet
the answer no longer appears to apply?
I agree and even worse is when noone has answered it all and it's the
only hit. Or my favourite: when your (generic and/or exact) search query
yields no hits at all.
BR,
Simon
--
Remember: if a new user has a bad time, it's a bug in logstash.
Apache, Apache Lucene, Apache Hadoop, Hadoop, HDFS and the yellow elephant
logo are trademarks of the
Apache Software Foundation
in the United States and/or other countries.