[syslinux] isohybrid has 2 variants

[dave madsen]

Ady --

Frankly, I was hoping for a somewhat less judgmental response, perhaps even
a conversation.

My interest is in expanding the usefulness of the the documentation to
various audiences.  I have noticed over a long period that there have been
many questions to the list which presumably could have been avoided by
having appropriate documentation. Many answers have been of the form "well
the Wiki is incomplete and/or hasn't been updated and/or information is in
the wrong place, and so you need to know (xyz)".

Since you don't know what work I've done, I'd like to let you know that
your apparent assumption (based on your lecture) that I've not written
code, haven't written documentation, and do not understand the trade-offs
of information inclusion vs. linking vs. searching is presumptive, and,
incidentally, false.

Please note that I DO consider the quality of documentation "a practical
matter", that's why I posted.  If it is not, then why not just delete the
Wiki and save time maintaining it?  Let the users read the code -- after
all, it *is* the authoritative source!

Unlike you, I'm a lurker here, not a contributor, so I will be silent from
now on.



On Tue, Jun 24, 2014 at 4:18 PM, Ady <ady-sf at hotmail.com> wrote:

>
> > > > When
> > > > information is too-technical, or the wording sounds too-technical,
> > > > most users won't even read it.
> >
> > Although a "list lurker", I'd like to make a brief comment (stating the
> > obvious).
> >
> > Documentation will have different audiences, ranging from [sometimes
> > not-clueful] end-users to people trying to make distros bootable under
> > different conditions, to those who may want to learn enough background to
> > contribute to the project in some way.
> >
> > Each will complain differently when they use the Wiki, not only because
> the
> > information they're looking for is different, but because the background
> > each brings with them is different.
> >
> > I believe that reorganization of the documentation keeping this in mind
> > would be the "best" solution, rather than debating what to leave in or
> cut
> > out.  There have been multiple times I've been interested in a piece of
> > software and wanted to find out its history so I could orient myself, and
> > some "helpful" soul had decided that all the old stuff was unnecessary
> and
> > deleted it.  Conversations with long-time developers (when I could find
> > any) were required to learn things.  It wastes time and is painful for
> > everyone.
> >
> > (No, I'm not volunteering -- I knew you were gonna ask.  I don't know
> > enough to be able to make good decisions, someone would have to review
> and
> > clean up after me.)
> >
> > Please don't delete "old" or "useless" stuff.  It *will* be useful to
> > *someone*.
> >
> > Also, If I'm trying to learn more about booting, it makes sense to dig
> into
> > this project.  If you delete technical information that I need to know,
> > could I Google for it?  Sure -- but it would be a lot easier if the
> > information were already here.  It's a fine line between deciding what
> > information should be included in the docs here and what should be
> searched
> > for.  But remember that searching isn't free in cost of the user's time.
> >  If you delete information, at least insert a link to the information
> > elsewhere on the web (even knowing the link might go stale or missing).
> >
> > As far as marking software frozen, I would suggest that "frozen" is a
> value
> > judgement:  if I want to work on it, then it's not frozen anymore, right?
> >  If it's felt that it's deprecated or superseded for some reason, the
> > software should be annotated as such, together with the reason(s) why and
> > what would be required to make it up-to-date (if possible).  If I'm then
> > attracted to use it or (God forbid!) work on it :-), then I would know
> what
> > I'm getting into and be able to intelligently decide if it's worth it and
> > how I might be hurt in the process.
> >
> > Sorry to interrupt your conversation.  "Now back to our regularly
> scheduled
> > programming".  Thanks for reading.
>
> Unfortunately, there is no way to write "for everyone". If the text
> is too-technical, common users won't read it, much less understand
> it. If it is "too-superficial", experienced readers won't read it and
> it would be almost useless for common users too.
>
> To be able to collaborate with writing helpful documentation, a
> potential writer would need to understand at least a little more than
> the common "incidental or "sporadic" user.
>
> To be able to collaborate with code, being capable of reading code is
> not optional. If someone wants to look a little back in history,
> looking at the git logs/diffs/commits is one possibility.
>
> So the wiki can't "contain everything", or use a "keep all info in,
> include all, don't delete any detail" style. This is not exclusive to
> the Syslinux wiki.
>
> Copying information that is available elsewhere is also not a good
> idea. When one site updates its content, users reading both texts
> can't decide which one is accurate. For these cases, linking to
> several alternative sources is more appropriate.
>
> Just as example... If someone has problems with some tool that uses
> Syslinux for building a USB bootable drive using FAT, he should ask
> that tool's developers, or maintainers, or in the respective distro's
> forum, before asking in #syslinux, or in this Syslinux Mailing List.
> It shouldn't be expected for the Syslinux wiki to solve all the
> issues for "something not booting". And yet, it is rare to see here
> (or in #syslinux) someone receiving no answer at all.
>
> Certainly more development-time/brains/fingers are needed, specially
> considering the expectations users frequently have about Syslinux.
>
> Regarding users that need to invest more time searching, "waa waa
> booo..." :D. Someone has to invest time to write code, someone has to
> invest time writing documentation, someone has to invest time
> testing... I wish the Syslinux Mailing List content would be indexed
> by respectable popular web search engines as it used to be (before
> 2012-Oct), but other than that... Users can type some words too; they
> will find the information.
>
> Let's move on to more practical matters.
>
> Regards,
> Ady.
>
> _______________________________________________
> Syslinux mailing list
> Submissions to Syslinux at zytor.com
> Unsubscribe or set options at:
> http://www.zytor.com/mailman/listinfo/syslinux
>