I'm open to suggestions around the format. The outline (as originally intended) was:
1. High-level overview of the issues being addressed 2. What the rule does specifically 2.1 What are the patterns that are flagged as warnings 2.2 What are some patterns that aren't flagged 2.3 Any options for the rule 3. When not to use it 4. Further Reading People seem to be munging together 1 & 2, which I think does a disservice to the reader. 1 is really intended to be a short narrative about the topic (outside of ESLint) while 2 is much more about the implementation of the rule. Here are some good examples: https://github.com/nzakas/eslint/blob/master/docs/rules/strict.md https://github.com/nzakas/eslint/blob/master/docs/rules/new-cap.md https://github.com/nzakas/eslint/blob/master/docs/rules/no-global-strict.md https://github.com/nzakas/eslint/blob/master/docs/rules/no-debugger.md Really, I want to inform the user enough about the circumstances surrounding the rule so they know whether or not to enable it. On Fri, Dec 20, 2013 at 10:47 AM, Ian Christian Myers <[email protected]>wrote: > Can you give an example of a rule that has good documentation that can be > used as a example? > > Also, I find that with some of the rules the documentation becomes > repetitive because the format calls for prose in two places—at the > beginning as an overview of the rule and the justification for it and then > again after the first example where it seems like you're supposed to talk > about the specific cases when the rule will of will not warn/error. Would > you be open to iterating on the documentation format? Perhaps simplifying > the format into one explanatory paragraph followed by some better, more > real-world examples of the error and the best way to re-write to avoid the > error? > — > Sent from Mailbox <https://www.dropbox.com/mailbox> for iPhone > > > On Fri, Dec 20, 2013 at 10:29 AM, Nicholas Zakas < > [email protected]> wrote: > >> Hi all, >> >> Just a heads up. I've been going through the rule documentation and we >> have some pretty lousy documentation on a fair number of rules. As such, >> I'm going to be much more strict about the documentation that's accepted >> with rules. One of the things that is going to set ESLint apart from JSHint >> and JSLint is that we are going to have mountains of useful documentation. >> >> Just FYI. :) >> >> -- >> >> ______________________________ >> Nicholas C. Zakas >> @slicknet >> >> Author, Professional JavaScript for Web Developers >> Buy it at Amazon.com: >> http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3 >> >> -- >> You received this message because you are subscribed to the Google Groups >> "ESLint" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> For more options, visit https://groups.google.com/groups/opt_out. >> > > -- ______________________________ Nicholas C. Zakas @slicknet Author, Professional JavaScript for Web Developers Buy it at Amazon.com: http://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691/ref=sr_1_3 -- You received this message because you are subscribed to the Google Groups "ESLint" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/groups/opt_out.
