Re: Improving the Contributors Guide and LilyDev

[Paul Morris]

> On May 3, 2015, at 11:02 PM, Carl Sorensen <address@hidden> wrote:
> 
> I think that it would be great to have you prepare patches for the CG.
> The CG is the least-reviewed manual in our set, so it's probably the
> easiest manual for which to get patches approved.

Will do, once this discussion winds down, and maybe I’ll wait until the new 
LilyDev arrives.  (Well, I can definitely do the specific things I've 
identified, not sure I can take on larger scale edits at this point.)


>> (And/or in the CG walk the reader through the steps to change the editor
>> settings.)
> 
> This is an immediately-accessible thing to do.

Yes, I’ve made a note to add this.


>> The indicator of the current git branch (in the command line prompt) is
>> not set up in the .bashrc file as it says it is in CG.  This should
>> already be set up.  See CG 3.2.1 Configuring Git, where it says:
>> Finally, and in some ways most importantly,
>> let¹s make sure that we know what branch we¹re on.
>> If you¹re not using LilyDev, add this to your Œ~/.bashrc¹:
>> export PS1="address@hidden \w\$(__git_ps1)$ "
> 
> Personally, I'd love to see a patch for this in the CG (and it would be
> nice to have it in LilyDev out of the box).

This is actually already in the CG (well I guess it doesn’t spell out *how* to 
add that line to the ~/.bashrc file).


> A CG entry that would tell how to install geany and/or gedit would
> certainly be helpful.

Agreed (although if they’re preinstalled maybe it’s not needed…)


> GNU's formatting style is less specific in the form of tabs/spaces, IIRC.
> We've had this discussion, and I believe it's a good idea to exclude tabs,
> and only use spaces in the source code.  astyle isn't needed if you are
> careful with your editing and match the existing code. If you make a
> mistake, it will be pointed out in review, and it's simple to fix it.

Ok.  


> Your notes on the CG are excellent in general.  I hope you will prepare
> some patches!

Thanks!  Will do.


> 2.3 is about getting it set up with LilyDev.  4.x is about general work
> whether with or without LilyDev.  We are much stronger about recommending
> the use of LilyDev than we were when the CG was originally written, so
> perhaps it's time to make a change here.

Hmmm… maybe that’s what I’m noticing / picking up on?  It seems that some 
sections assume you’re using LilyDev while others don’t.  


>> C. A Few General thoughts FWIW:
>> 
>> Since those working on the documentation, website, or even source code
>> may not be programmers but they still have to learn how to use git etc.
>> keep non-programmers in mind as a primary audience for the CG.  For
>> example:
>> 
>> Assume the reader is using LilyDev.  Those that aren't using LilyDev will
>> have more experience and need less from the CG, so better to pitch things
>> to those who need the most help.
> 
> I'm not sure I agree with this.  The CG is the only place in the manuals
> that we provide help for those who are not using LilyDev.  And there are
> some quirks of LilyPond that need to be part of the docs in my opinion.
> 
> I don't have a particular patch to comment on here, so I can only deal in
> generalities.  But maybe we have a chapter that is something about
> "Developing without LilyDev".
> 
> We certainly want to make the CG accessible for new users/developers.  But
> we also want to have the CG useful for old developers and those
> experienced with other software development environments.   Perhaps we
> need to clarify these two different use cases, and separate them out more
> carefully in the CG.  But IMO we need to avoid making the CG only useful
> for newbies.

Yes, I could have worded that better.  I didn’t mean to suggest to focus 
exclusively on newbies, just that both use cases should be covered, and err on 
the side of the newbies since they are new.  But then I would say that, being 
more of a newbie…  ;-)

Anyway, as you suggest, this is probably better discussed in terms of 
particulars, actual cases, rather than in generalities.

> The CG has historically had a much less stringent editorial review
> process.  Basically we said to developers "If there's something you think
> should go in the CG, put it there."  Perhaps it's time to be more
> selective, and see how we can tailor a short, accessible section of the CG
> for new users.  And then we could leave the other stuff in chapters that
> are aimed at experienced developers.

Maybe, although I think having separate sections that cover similar things at 
different experience levels is often not the best approach.  It can feel 
fragmented and unwieldy.  

I’d rather have something like occasional sidebars (or boxes with a different 
color background) that are labelled “for beginners” or “for more advanced 
users” or “for those not using LilyDev” (etc.) that separate out some content 
from the main text but keep it right there for when you need it.  Then there 
can be one “canonical” account of how to do something, but it is easy for 
readers to skip the parts that they don’t need and focus on those they do.  And 
newbies can learn more as they go if they want.  That’s my take anyway.

Of course in some cases it may make sense to just have a separate section.

> Thanks again for looking at this.  Certainly improving the CG is an
> important part of the health of LilyPond.

Glad to help,
-Paul