cschem - howto contribute

Any contribution is valuable. However, any contribution costs too, not just for the contributor but for the community: the time to read it, test it, maintain it, etc. In the best contribution the cost/benefit ratio is strongly biased toward the benefit. This howto gives a few pointers how this cost/benefit ratio could be improved.

Do's	Dont's
focus: if the current design process is about aspect foo, please don't write long essays on how aspect bar is affected unless it's absolutely necessary to understand how foo is affected. split things up; if there are 4 sections of a design doc you have comments about, please start 4 separate thread for them. proper referencing; if your comment is about a specific section, use the section label (e.g. "{des1:4}") for reference. If the whole mail or thread is about such a section, best put the reference in the subsect. concentrate on what problem we need to solve, not on which technology is used in the solution; e.g. "we want this part to be user scriptable" is a good consideration; "we want this part to be written in lua" is a bad one. Generally speaking: distinguish between design and implementation details. Focus on the design.	Avoid sending a single huge mail commenting every second line of a chapter: that will be very hard to handle for everyone else. Avoid writing verbose, especially about "background information"; please try to keep text as short as possible. Please don't get stuck on an implementation detail; it's impossible to design cschem to 100% match everybody's preference on every little detail. If it matches only 70%, please live with it for now, if the design is strong, it will be easy to provide alternatives later. Do not hijack threads; if you want to steer the discussion in another direction, it's okay to reply to a mail in a thread, but please do change the topic so people know it's a new (sub)thread.

Do's

Dont's

focus: if the current design process is about aspect foo, please don't write long essays on how aspect bar is affected unless it's absolutely necessary to understand how foo is affected.
split things up; if there are 4 sections of a design doc you have comments about, please start 4 separate thread for them.
proper referencing; if your comment is about a specific section, use the section label (e.g. "{des1:4}") for reference. If the whole mail or thread is about such a section, best put the reference in the subsect.
concentrate on what problem we need to solve, not on which technology is used in the solution; e.g. "we want this part to be user scriptable" is a good consideration; "we want this part to be written in lua" is a bad one.
Generally speaking: distinguish between design and implementation details. Focus on the design.

Avoid sending a single huge mail commenting every second line of a chapter: that will be very hard to handle for everyone else. Avoid writing verbose, especially about "background information"; please try to keep text as short as possible.
Please don't get stuck on an implementation detail; it's impossible to design cschem to 100% match everybody's preference on every little detail. If it matches only 70%, please live with it for now, if the design is strong, it will be easy to provide alternatives later.
Do not hijack threads; if you want to steer the discussion in another direction, it's okay to reply to a mail in a thread, but please do change the topic so people know it's a new (sub)thread.