Syslinux - Feb 2015 - hello world

Hi,

As someone who just recently came to the Syslinux project, with a
different agenda but still a Syslinux noob maybe I can add my
perspective.

The Doc/Wiki makes perfect sense from a DEVELOPERS point of view, but
I think the point here is maybe from a USERS point of view not so
much.

Even approaching syslinux with the purpose of building a custom .c32
module and leveraging the core syslinux boot infrastructure:

 I didn't get/see the VARIANT/variant distinction.  When I read that
it was an "of course" moment but I do think that it could be
emphasized to help other noobs. Yes I see it now on the wiki home page
but I initially thought that was an artifact of some wiki page naming
convention.

I too was bit by the library code issue but saw it as a lack of
knowledge on my part.  That's not how some (most?) USERS would see it
though.

I really don't know what to say about the active partition issue, That
is how most boot loaders work and you will run into the issue with
just about any other boot loader.

Finally, if LILO is going EOS at the end of the year it might not be a
bad idea to create a migrating from LILO page and featuring it
prominently on the wiki home page.  I'm not suggesting a huge HOWTO
may be just a simple here are the basic differences we know about, the
VARIANT/variant convention, modules/libraries are located in
<bios|efi32|efi64>/com32/modulename, most (all?) com32 modules will
require the library code and if you're booting from a dos fs use
syslinux, if you're booting from a Linux fs use extlinux, etc.
----------
Mike

> Hi,
> 
> As someone who just recently came to the Syslinux project, with a
> different agenda but still a Syslinux noob maybe I can add my
> perspective.
> 
> The Doc/Wiki makes perfect sense from a DEVELOPERS point of view, but
> I think the point here is maybe from a USERS point of view not so
> much.
> 
> Even approaching syslinux with the purpose of building a custom .c32
> module and leveraging the core syslinux boot infrastructure:
> 
>  I didn't get/see the VARIANT/variant distinction.  When I read that
> it was an "of course" moment but I do think that it could be
> emphasized to help other noobs. Yes I see it now on the wiki home page
> but I initially thought that was an artifact of some wiki page naming
> convention.
> 
> I too was bit by the library code issue but saw it as a lack of
> knowledge on my part.  That's not how some (most?) USERS would see it
> though.
> 
> I really don't know what to say about the active partition issue, That
> is how most boot loaders work and you will run into the issue with
> just about any other boot loader.
> 
> Finally, if LILO is going EOS at the end of the year it might not be a
> bad idea to create a migrating from LILO page and featuring it
> prominently on the wiki home page.  I'm not suggesting a huge HOWTO
> may be just a simple here are the basic differences we know about, the
> VARIANT/variant convention, modules/libraries are located in
> <bios|efi32|efi64>/com32/modulename, most (all?) com32 modules will
> require the library code and if you're booting from a dos fs use
> syslinux, if you're booting from a Linux fs use extlinux, etc.
> ----------
> Mike
> _______________________________________________
> Syslinux mailing list
> Submissions to Syslinux at zytor.com
> Unsubscribe or set options at:
> http://www.zytor.com/mailman/listinfo/syslinux
> 
 
FWIW, most wiki pages I have mentioned in this email thread were 
written targeting common users.

For example the "Library modules" wiki page uses language and terms
for
common users, and it includes the "whys" and the "wheres".
This page
answers (or at least tries to) some of the issues that common users 
have with c32 dependency modules, independently of the bootloader 
variant (since the matter is, indeed, relevant for c32 modules and not 
dependent on which Syslinux variant is being used). Users in forums, 
irc, mailing lists, bug reports... can follow links to this page. It 
also mentions some differences regarding prior versions.

And, talking about versions, this is another factor in documentation. 
For example, listing library modules needed by menu.c32 (or for each 
c32 module) in its own page would be very confusing for users of prior 
versions, in which each c32 module is (for common users) "standalone".
Moreover, it would be prone to misunderstandings when one c32 module 
might change its (c32 library modules) dependencies according to the 
Syslinux version, or when the reader's prior knowledge varies.

Instead of repeating information in several places (which makes it much 
harder to maintain), links were added, pages were classified into wiki 
Categories, and pages such as "Common Problems" and "Hardware 
Compatibility" were expanded. Updating the information about the c32 
dependencies in one wiki page is much easier than updating dozens of 
pages, and readers can follow links, if they need/want to.

Please keep in mind that different types of users, with different 
levels of knowledge, require different types of reading, wording, etc. 
Therefore, as I said, there is no way to simultaneously satisfy all 
these types of readers. It requires a balance.

For example, the "Library modules" wiki page might seem too-long for 
some readers, and not enough for others. Similarly, the "Install" wiki
page.

Another example: the wiki pages for the installers (commands) mention 
"mount", "umount", "format file system",
"FAT"... Some users might
think these issues should also be covered in the Syslinux wiki, in 
spite of not being part of Syslinux itself. There should be some base 
line, somewhere. Otherwise, we could end up documenting simple math too 
:D.

Considering that all the Syslinux subjects are technical by nature, 
there is a practical limit to how much the wiki pages can be simplified 
in wording style and expanded in length. Again, balance. There is 
certainly a valid place for a variety of auxiliary user-friendly tools 
using Syslinux in the back, so users having problems with Syslinux 
might want to use such tools.

Please let me reiterate:
_ feedback is very important and it is very much taken into 
consideration; and,
_ the wiki indeed needs several improvements.
>From those users that are authorized to edit pages in the wiki, not 
many are actively updating it. From those authorized to edit pages in 
the Syslinux wiki in general, very few are authorized to edit the main 
page(s) (which is the main answer to this feedback). There are even 
less people allowed to edit the official documentation included in the 
official archives (which is why the latter is more outdated than the 
wiki).

Distros such as Gentoo, Arch, Puppy... also have their own 
documentation about Syslinux, or about Syslinux packages. There are 
many articles, blogs, auxiliary tools... This is also a very useful way 
of improving documentation. And when something specific is not clear, 
here we are, in this Syslinux Mailing List.

I am not rejecting the feedback about documentation. As I said, we 
_know_ there is place for improvements (and I am not just saying this 
in a generic way; I know of specific points for improvements). On the 
other hand, and in no way opposing or impeding documentation's 
improvements, I'd rather see the Syslinux developers actually writing 
code. In theory, user documentation should be part of development. In 
practice, The Syslinux Project simply lacks of enough resources.

So, the intention of this email is not to reject nor disregard the 
provided feedback. It _will_ be considered.

BTW, using the "search" feature in the wiki is usually helpful.

Please, do not be discouraged by my words; on the contrary. I am 
sincerely 
hoping and wishing for more feedback and more contributions (specially 
resolving bugs), not less.

Thank you and Regards,
Ady.

On 02/01/2015 08:12 PM, Ady via Syslinux wrote:


Ady,

Thanks for that:

"So, the intention of this email is not to reject nor disregard the
provided feedback. It _will_ be considered."

... it's all that can be expected.  And it's natural for you to defend 
the status-quo.  It must not become a contest.  However, once one has 
become expert in something one most often forgets what it was like not 
to know.  The expert can not help but be what he is when writing a doc.  
IMHO every doc needs to be vetted by raw noobs so that they can say what 
only they can say, which is whether the doc was helpful to *them*.  It's 
the only time when the opinion of the aggregate of noobs should trump 
the opinion of the experts.
> FWIW, most wiki pages I have mentioned in this email thread were 
> written targeting common users. For example the "Library modules"
wiki
> page uses language and terms for common users, and it includes the 
> "whys" and the "wheres". 

Sure, so let the common user let you know if you've hit the nail on the 
head.
> Instead of repeating information in several places (which makes it 
> much harder to maintain), links were added, pages were classified into 
> wiki Categories, and pages such as "Common Problems" and
"Hardware
> Compatibility" were expanded. 
Right. The trick is either make pages standalone, or somehow crosslink 
them in some way that makes it easy to know if you are reading specific 
or general information.  So long as it is clear.
> Therefore, as I said, there is no way to simultaneously satisfy all 
> these types of readers. It requires a balance. 
Yes, quite true.  I have no more weight in my feedback than anyone else, 
but I give it FWIW.
> For example, the "Library modules" wiki page might seem too-long
for
> some readers, and not enough for others. 
Myself I've always liked a 'quickstart' page, for people who just
want
to get going, or who already have an understanding of basic things.  
Then the main text with footnotes that go off into deep details.  The 
wiki is as good as normal.  The only place I know where excellence is 
almost always achieved is in the Arch docs. Nuts, I run Debian, but I go 
to Arch for answers.