Re: an example of minimal example (issue4636082)

[pkx166h]

Hello, my comments inline.

James


http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi
File Documentation/web/community.itexi (right):

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode283
Documentation/web/community.itexi:283: The simpler the example is, the
quicker potential helpers can
The tinier the example, the simpler it is and therefore, the quicker...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode287
Documentation/web/community.itexi:287: A simple example demonstrates
that you have put effort towards
A tiny example also demonstrates to others on the email lists that some
kind of effort has been taken to...

[PS Are we talking 'simpler' or 'tinier' here? While I can see that both
work, they are two different ideas and you are already moving away from
'tiny'. Can we stick to tiny?]

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode289
Documentation/web/community.itexi:289: input, it looks like they don't
care how if we help them or not.
solving the problem yourself. Whereas overly complex, large or unedited
examples look like no effort has been made to try to attempt to solve
the problem yourself and can discourage others from helping.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode292
Documentation/web/community.itexi:292: Creating a tiny example forces
you to understand what is
A tiny example can also help you to ...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode296
Documentation/web/community.itexi:296: insufficient understanding of
LilyPond, not an actual bug!
...then the problem is usually due to a lack of understanding of how the
LilyPond syntax works.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode305
Documentation/web/community.itexi:305: @subheading How do I create them?
How to create them.

[we try to not personalise the text or talk in first/second person]

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode311
Documentation/web/community.itexi:311: Include the \version number.
Include the LilyPond @code{\version} number you are using.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode314
Documentation/web/community.itexi:314: Make it small!  Examples about
spacing or page layout might
Keep it tiny! Examples about...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode320
Documentation/web/community.itexi:320: or @address@hidden @dots{} 
address@hidden)}
sections of your file.  If you can
..or @address@hidden @dots{} address@hidden)} sections of your file first. If 
you can...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode321
Documentation/web/community.itexi:321: comment something while still
demonstrating the main idea, then
comment something out while ...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode322
Documentation/web/community.itexi:322: remove the commented-material!
remove the commented material completely from your example.

[no need for all the exclamations]

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode325
Documentation/web/community.itexi:325: Avoid using complicated notes,
keys, or time signatures, unless
..notes, keys or time signatures, unless...

[remove comma]

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode330
Documentation/web/community.itexi:330: is about those particular
commands.
[I'd use the word 'specific' instead of 'particular' here]

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode334
Documentation/web/community.itexi:334: (how the correct output should
look like).
If possible, attach a small image file of what you want the correct
output to look like as this will help us clarify exactly what the
problem is.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode375
Documentation/web/community.itexi:375: quite often 4 lines are enough to
demonstrate the problem!
[we've already said this above - "Examples about spacing or page layout
might require many bars of music, but most issues can be reproduced
using less than a single measure" why repeat it (and differently)?]

http://codereview.appspot.com/4636082/