[syslinux] isohybrid has 2 variants

Ady
Tue, 24 Jun 2014 22:18:26 -0000

> > > 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.