Guidance on writing: person, passive/active voice...

[OriolAbril]

Is there a preferred way to address users? Especially for tutorials where we want to give instructions to the reader. Guidance on commenting and explaining code: explanation in markdown above the code cell? below? general explanation in markdown only and implementation details as comments within the code? glossary terms, how do we know if a term should be explained in the notebook or in the gossary, or in both even. other potentially controversial topics?

cc @martinacantaro

It doesn't need to be very extensive and it can even be mostly links to other pages, but I think it will make both writing and reviewing notebooks easier

[chiral-carbon]

adding onto this, if the author wants to discuss their approach, thought process or opinions on using certain libraries in the description markdown cells, should there be a guideline for that?

the notebook GLM out-of-sample predictions specifically made me ask this.

it does sound strange to put a rule on someone expressing their thoughts while demonstrating something in a notebook but I was wondering about it anyway, especially if we are updating the notebooks to use new dependencies but the author has talked about their approaches using the older dependencies used in that notebook.