You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I was cleaning up the problem files for functional-javascript-workshop & using learnyounode as an example, but it looked like the style on learnyounode wasn't totally consistent internally either.
As more of these lessons are created and added to nodeschool.io, it seems it would be prudent to have some common style guidelines for problem descriptions. Not that authors would have to follow them, but as recommendations. Having common problem description style across lessons would allow learners to orient themselves to a new lesson & locate information within the problem definition more easily.
I propose creating a style guide that covers:
How to delineate sections (e.g. "use ## h2s to delineate sections in a problem description)
Common sections & titles (e.g. "Task (or Goal), Arguments, Input, Boilerplate, Hints, Extra Credit (goals beyond main goal like 'don't use a loop') and Additional Resources etc. are section headings; not all section headings are appropriate for each problem of course")
Section order (e.g. "boilerplate" section always comes last, "Task" always comes first etc.)
Recommendations for coloring things (since colors are being used now it would make sense for them to be consistent)
Recommendations for length (e.g. lessons should typically printable in <100 lines, longer than this consider refactoring/breaking up)
I know some of these sound too prescriptive- I'm just brainstorming; there are exceptions to every rule & in any event no one would have to follow the style guide. I know that if I were lesson author, however, such a style guide would make it easier to author a lesson because I wouldn't have to consider all these questions (how do I delineate a section which should come first etc.) I could just follow the example.md
If this is something BDFL et al. are interested in I can work on a draft.
The text was updated successfully, but these errors were encountered:
I was cleaning up the problem files for
functional-javascript-workshop
& usinglearnyounode
as an example, but it looked like the style onlearnyounode
wasn't totally consistent internally either.As more of these lessons are created and added to nodeschool.io, it seems it would be prudent to have some common style guidelines for problem descriptions. Not that authors would have to follow them, but as recommendations. Having common problem description style across lessons would allow learners to orient themselves to a new lesson & locate information within the problem definition more easily.
I propose creating a style guide that covers:
## h2s
to delineate sections in a problem description)I know some of these sound too prescriptive- I'm just brainstorming; there are exceptions to every rule & in any event no one would have to follow the style guide. I know that if I were lesson author, however, such a style guide would make it easier to author a lesson because I wouldn't have to consider all these questions (how do I delineate a section which should come first etc.) I could just follow the example.md
If this is something BDFL et al. are interested in I can work on a draft.
The text was updated successfully, but these errors were encountered: