Syslinux - Jun 2014 - isohybrid has 2 variants

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

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
>

> 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.
> >
> 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.
> 
> 
> 
 
Hi Dave,

There is a chance I am misusing the English language.

I also consider documentation (and its discussion) a practical 
matter. We have been doing it for the last couple of days, and this 
is not the first time and not the only place.

When I said "let's move on to more practical matters", I don't
mean
to disregard / discard additional opinions.

If we were discussing some "one-time hard copy edition", we would 
need much more detailed discussion.

Different points of view have been expressed, and considering that 
the documentation we talk about is a wiki, we can improve it on time. 
So by "practical" I mean that Thomas could/should go ahead, and 
perhaps later comments and questions from users / readers would let 
us know how to improve it.

We can keep discussing, but if the page is not started then 
effectively we do "nothing". I mean "nothing" in terms of
users.

As I said before in a prior email, my opinion has the same value as 
anyone's, so I don't understand why my prior email sounds judgmental. 
Again, perhaps I am misusing (or misunderstanding) the English (which 
is not my natural) language.

I still think that it is very difficult to write "for everyone", and 
sometimes writing (too many) technical details is not helpful for 
users. Let me give an example.

There is one ("error") message that has been asked about many 
(really, many) times, "not a COM32R image". Almost every 
Linux-related forum, mailing list... have seen this question. Common 
users by now could search the question and find its solution. And 
yet, they keep asking again.

The matter is documented in the wiki too. The solution (in succinct 
words): all files related to Syslinux shall match the same version.

Typically, the problem shows up with USB drives that were created by 
one tool for one distro, and now the user tries to use it for another 
distro that comes a different version of Syslinux. Some users end in 
"Syslinux doesn't work for me".

Now, some (somewhat rhetorical) questions (and I am writing this with 
respect and not with any "tone"). How much technical details should 
we provide in the wiki?

Should we just explain that all c32 files and the boot loader shall 
come from the same exact version of Syslinux?

Or perhaps we should list every single tool and method with its 
corresponding current Syslinux version and update the list with every 
change / update? In such case, should we also add a "howto" for these 
tools?

Or maybe we should explain that there are COMBOOT-16, COM32, COM32R, 
ELF formats, depending on the version of Syslinux and that they are 
incompatible between each other?

Perhaps we should evaluate which versions of certain c32 files "just 
happen" to be usable with other versions of the boot loader?

Should we get into the inner details about COMBOOT-16... ELF, so the 
user that just wants to be able to boot his USB drive with the new 
version of some Live distro can achieve his goal?

I think that all this information could be useful for some group of 
readers, but I also think that posting all this information together 
in one single wiki page would be a mistake.

Certainly the common user won't be interested in reading about the 
ELF format - after all, he just wants to try this new Live distro. 
Meanwhile, those with the ability and interest to understand the 
different formats of the Syslinux modules would be bored with at 
least part of the information that targets common users.

BTW, at least parts of the different matters I just mentioned happen 
to be in (individual, separated) pages or somewhere in the Syslinux 
docs.

Asking ourselves the question "who is the target reader for this 
particular 
information / wiki page" is relevant.

The documentation of The Syslinux Project is not as up-to-date as we 
all would 
want it to be, and (not all but) some of the comments about "this X 
mater 
should be updated in the wiki" are justified. Yet, someone has to 
dedicate time 
to actually write it, and in such a manner that would be effective 
for common 
users.

Now, if there is something specific that the new isohybrid page 
should include, 
or that it shouldn't, please speak up so we can all effectively 
improve it.

In fact, if there is anything about Syslinux anyone wants to 
contribute with / 
report / suggest..., please, please speak up.

Best Regards,
Ady.