Re: openLilyLib website

[Urs Liska]

Hi Simon,

Am Sonntag, den 23.02.2020, 18:42 +0100 schrieb Simon Albrecht:
> Hi Urs,
> 
> this looks great! As often, I can’t offer much more than applause
> and 
> some nitpicking…

Well, that's useful too.

> 
> On the ‘About LilyPond’ I’d rather write “GNU LilyPond is a music 
> notation program /strongly inspired by/ traditional craftsmanship”. 
> After all, the process of working with LilyPond doesn’t resemble 
> traditional craftsmanship at all…

Good point.

> 
> The use of the word ‘domain’ in the About/LilyPond and /openLilyLib 
> seems quite technical considering IIUC the site is supposed to be
> read 
> also by people without a background in software development…

I must say I'm pretty unhappy with that whole page. I actually replaced
the bullet list with some text just to be able to send that email to
the list.

The introduction on that page should be even shorter, but at the same
time more friendly, casual, positively inspiring than the current text
tending to be too technical and boring.

> 
> ‘Get started/Install openLilyLib’ has an instance of [oll-core} that 
> seems unintentional.

Thanks, had already been spotted and fixed (although not uploaded yet).

> 
> s/documenation/documentation

Thanks.

Best
Urs

> 
> … but generally, the texts seem very appropriate and useful :-)
> 
> Very best regards
> Simon
> 
> On 20.02.20 22:44, Urs Liska wrote:
> > Hi all,
> > 
> > as a starting point for a - hopefully - comprehensive documentation
> > effort I have finally updated https://openlilylib.org with a
> > completely
> > new website, which I'd like to have some feedback about and
> > contributions for.
> > 
> > There are several parts to that effort, most of which are
> > essentially
> > not started yet.
> > 
> >   * A general introduction website. This is basically complete and
> >     should finally give a proper introduction about what OLL "is"
> > and
> >     how it can be made to work
> >   * Independent sub-sites for each OLL package. These have not been
> >     written at all, only the links to empty starting pages work
> > without
> >     404 errors.
> >   * I've settled with MkDocs (https://www.mkdocs.org), which seems
> > to
> >     provide what I need, especially a suitable way to hook into and
> >     extend to our needs.
> >   * Each sub-site is maintained in a separate Git repository and
> >     included as a Git submodule, so it should be straightforward to
> >     manage independent authoring of the documentation by the
> > respective
> >     package maintainers.
> >   * There's a link to a contributor's guide, which is also
> > essentially
> >     empty, except for an entry page.
> > 
> > What I have so far is an infrastructure for textual, Markdown-
> > authored
> > manuals, although I have already created a plugin for LilyPond
> > syntax
> > highlighting using python-ly (
> > https://github.com/uliska/markdown-lilypond/).
> > 
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?), resulting in either HTML or Markdown documentation
> > that
> > can be automatically integrated in the "manual-style"
> > documentation.
> > 
> > Best
> > Urs
> > 
> >