[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Proposed additional info for Contributor's Guide 6.1, Introduction to we
From: |
Karlin High |
Subject: |
Proposed additional info for Contributor's Guide 6.1, Introduction to website work |
Date: |
Sat, 3 Dec 2016 20:05:38 +0000 |
So far on the lilypond-user list, I have witnessed 2 website-redesign
discussions. I gather there have been more in the past. Apparently the
usual pattern for these starts when someone with web development skills,
but no LilyPond contributor experience, looks at www.lilypond.org and
thinks, "This place needs help. Have they not heard about
$MYFAVORITECMS?" A sizable discussion results, with long-time LilyPond
contributors needing to repeatedly explain that lilypond.org has a lot
going on below the surface that is powerfully resistant to large-scale
changes. After various frustrations, the would-be contributor usually
gives up.
I like Urs Liska's idea of having a wiki or contributor guide entry for
what LilyPond web development work requires. Then future proposals for
website work could get a response with a link to the requirements, as
routinely as lilypond-user reminders about Minimal Working Examples, and
hopefully helping avoid further 100+ message discussions.
Although I don't have great experience with the LilyPond project, I'll
propose something based on what I've gathered so far, maybe it could go
on Contributor's Guide 6.1, Introduction to website work.
http://lilypond.org/doc/v2.19/Documentation/contributor/introduction-to-website-work
Apparently the LilyPond source file is
./Documentation/contributor/website-work.itexi
This is slightly repetitive of other parts of the Contributor Guide such
as section 5, Documentation work, in keeping with the Guide's title page
statement about contributors only reading sections relevant to them.
----
What you see in your browser at www.lilypond.org is not just a website.
It is the product of a vast system of technical documentation. The
documentation is written in a language called texinfo, which is standard
for GNU projects. Texinfo allows generating different output formats
from a single set of source files. This avoids needing different
documents maintained for online information and printed manuals. Since
there are currently 11 manuals for LilyPond, not including the
translations, having a single-source documentation format is very
important. At this point, LilyPond's texinfo output formats include HTML
for the website, PDF for printing, and the Info format used by UNIX-like
operating systems. Keeping information on the website updated is
automatic, as the web pages are generated when the documentation is
built using the GNU make system. But it also means that the web
development environment is unusual, and based on texinfo rather than
HTML and CSS.
It is quite common for a skilled web developer to look at the
lilypond.org website and reflexively propose a different system for
maintaining it. Such proposals may have great merit when considering the
website in isolation. However, the LilyPond project has limited
resources for maintaining and translating its documentation, which makes
up a major portion of the website. The idea of having to maintain the
website apart from the documentation is unlikely to be supported by the
developers and translators. Although there may be systems other than
texinfo that would meet the needs for generating the documentation and
website, there would need to be a compelling reason to make such a
change. Simply doing the same thing in a different way is unlikely to be
enough. This is a little like signage for highways and airports, where
current fashions are largely disregarded in favor of long-established
standards for presenting messages. Large-scale changes are rare and only
done with great effort.
For any such large-scale structural change to be considered seriously,
it would almost certainly require that its proposer have a considerable
track record with maintaining LilyPond's documentation and show evidence
of long-term commitment to the project.
But, smaller changes to the formatting and appearance of the website are
also needed, welcome, and much easier to have accepted. If you have
never contributed to the LilyPond project before, and want to work on
the website, a good starting point would be incremental changes to the
CSS file. This file can be found on the website at
http://lilypond.org/css/lilypond-website.css or in the LilyPond source
code at ./Documentation/css/lilypond-website.css
The Texinfo source files that generate HTML for the website are
----
End proposal. Following would be the @example box with the file paths;
perhaps the paths for CSS files just preceding would get something
similar. Accept, modify, reject, ignore with crickets - I'll be OK.
--
Karlin High
Missouri, USA
- Proposed additional info for Contributor's Guide 6.1, Introduction to website work,
Karlin High <=