While making some lesson modifications as part of the BugBBQ I started thinking that I would like some way to add comments in-line into the lesson. This would have a similar purpose to comments in code and would convey information such as: "What are we trying to convey here?", "how does this relate to other parts of the lesson?", "what pitfalls / misunderstandings are commonly experienced here?".
Currently Instructors.md is used to hold this information, but I think that in-line comments would encourage better documentation by contributors. To avoid cluttering the standard display of the the lesson materials I visualise these as being hidden by default, similar to the proposed mechanism for challenge solutions. A second option is to use code comments with <!-- --> delimiters, however that would involve examining the source to view comments and in my opinion would be suboptimal. I admit I haven't been following the lesson template development too closely, so please excuse me if this has already been considered or if the template is currently frozen. Feedback welcomed, Tom _______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/listinfo/discuss
