Misc suggestions for section §2.4 (and nested paragraphs) about polygen-docs HOT 3 CLOSED

In §2.4.2 the second example uses labels, a concept that has not yet been introduced to the reader. Maybe we can remove them from the example, so it becomes less confusing?

There are a couple of similar instances in both documents. I also found them confusing initially. It's also true that writing a specs doc without incurring in similar situations is not easy, but if it's avoidable I agree that it would be better to remove such examples and (if strictly required) provide a cross reference to the topic section (for the benefit of those who are re-reading the documents).

I think that readers tend to spend some time studying the examples in order to make sense of what they've learned so far, so I'm totally in favor for this type of revision. What do you think @alvisespano?

(Actually, this suggestion also applies to the italian documentation).

Yes, this would be better moved to an independent Issue, so I can track it under the mliestone for both documents. But first let's see what @alvisespano thinks about these changes.

EDIT: Now moved to Issue #32.

from polygen-docs.

@RBastianini, I hope you don't mind if I've edited the original post — because multiple issues are being mentioned here, I need the checklist so I can track which were fixed and which are still pending (I'm fixing all typos in a single commit, but will handle contents changes later on, to allow unrolling changes if the need arises).

from polygen-docs.

Ok for the typos and the modifications mentioned in the checklist above.
As for the wrong example with labels without having introduced them yet: yes, you're right, you can remove it. And replace it with something else without labels perhaps?

from polygen-docs.