On January 1, 2017 4:47:39 PM "Peter.Stein" <[email protected]> wrote:
I actually had a bunch of comments, but suspected they would not be well
received
Try us.
and thus tried to be diplomatic
I must have missed that. ;)
and productive by suggesting a
step-by-step HOWTO. It's needed, everyone knows what one is, and
shouldn't be difficult to put together by the live-build experts. You
wanted an improvement suggestion and I gave you a very "actionable" one.
I know how many hundreds of hours of my personal time went into the
original document before I called it quits and doubt your assessment of the
ease of replacing the current doc. Since it's "incomprehensible", it seems
it all needs to be replaced from scratch ... or was that hyperbole, perhaps?
I'm always reluctant to get into these "improvement" discussions because
the fact of the matter is you open source folks don't take constructive
criticism very well and invariably end up copping an attitude - like you
are now. I've developed software professionally for 35 years and can
state unequivocally that this documentation does not meet the
"production grade" standard.
I am not "you open source folks". I'm a person with feelings, not a bundle
of stereotypes. I'm particularly not impressed by you "pulling rank" by
trotting out your "senior developer" status when I haven't seen a single
line of code or sentence of doc contributed by you to this project. Show me
the code (or doc).
I hear what you're saying about limited
resources and community efforts, but as the old saying goes "the road to
hell is paved with good intentions". At some point somewhat needs to
step back, take a deep breath, and do an honest assessment to determine
what if any improvements are needed.
I was that someone. I did that assessment, and this is what, within a
reasonable amount of time, I managed to accomplish to cut through the
information-dense manual and try to guide any new user through getting
oriented. I hope you've read it and tried at least this "crash course"
outline. If you did, please tell me what you thought of it:
https://debian-live.alioth.debian.org/live-manual/stable/manual/html/live-manual.en.html#8
I know it's just a small thing, but it's what time and energy allowed in
lieu of a more ambitious total rewrite, which I was painfully aware was
needed, but lacked the resources to carry out.
But that day has come and gone. What's left of the team is just keeping
this doc, and live-build itself on life support. The main thrust of
development is now in live-wrapper. So my honest assessment is: live-manual
is imperfect, but it's the doc we have. If it falls short of your
expectations, it falls on you, the users who still care about it, to make
it better, because it's not likely anyone else will. That's not "copping an
attitude". That's just giving you my experienced opinion on the state of
things.
Griping from the user community
should not be the impetus for change. That's my $.02. ;-)
So if you truly believe that, switch from griping to contributing!
Ben
