diff --git a/compiler/qsc_linter/src/lib.rs b/compiler/qsc_linter/src/lib.rs
index 8538209d87..a2ddb91464 100644
--- a/compiler/qsc_linter/src/lib.rs
+++ b/compiler/qsc_linter/src/lib.rs
@@ -38,7 +38,7 @@
 //! ```
 //! declare_ast_lints!{
 //!   ...
-//!   (DoubleParens, LintLevel::Warn, "unnecesary double parentheses"),
+//!   (DoubleParens, LintLevel::Warn, "unnecessary parentheses", "remove the extra parentheses for clarity"),
 //! }
 //! ```
 //!
@@ -52,7 +52,7 @@
 //!         if let ExprKind::Paren(ref inner_expr) = *expr.kind {
 //!             if matches!(*inner_expr.kind, ExprKind::Paren(_)) {
 //!                 // we push the lint to the buffer
-//!                 push_lint!(Self, expr.span, buffer);
+//!                 buffer.push(lint!(self, child.span))
 //!             }
 //!         }
 //!     }
diff --git a/compiler/qsc_linter/src/lints/ast.rs b/compiler/qsc_linter/src/lints/ast.rs
index 5aa45851b1..27c9362211 100644
--- a/compiler/qsc_linter/src/lints/ast.rs
+++ b/compiler/qsc_linter/src/lints/ast.rs
@@ -6,6 +6,23 @@ use crate::linter::ast::declare_ast_lints;
 use qsc_ast::ast::{BinOp, ExprKind, Lit, StmtKind};
 use qsc_data_structures::span::Span;
 
+// Read Me:
+//  To add a new lint add a new tuple to this structure. The tuple has four elements:
+//  `(lint_name, default_lint_level, message, help)`
+//
+//  where:
+//   lint_name: Name of the lint.
+//   default_lint_level: Default level for the lint, can be overriden by the user in qsharp.json.
+//   message: Message shown in the editor when hovering over the squiggle generated by the lint.
+//   help: A user friendly message explaining how to fix the lint.
+//
+//  Then, add an `impl lint_name` block adding the lint logic.
+//
+//  After adding a lint you need to go language_service/code_action.rs and add a Quickfix
+//  for the newly added lint (or opt out of the Quickfix) in the match statement in that file.
+//
+//  For more details on how to add a lint, please refer to the crate-level documentation
+//  in qsc_linter/lib.rs.
 declare_ast_lints! {
     (DivisionByZero, LintLevel::Error, "attempt to divide by zero", "division by zero will fail at runtime"),
     (NeedlessParens, LintLevel::Allow, "unnecessary parentheses", "remove the extra parentheses for clarity"),
diff --git a/compiler/qsc_linter/src/lints/hir.rs b/compiler/qsc_linter/src/lints/hir.rs
index b4321c4bd4..d5db771b5a 100644
--- a/compiler/qsc_linter/src/lints/hir.rs
+++ b/compiler/qsc_linter/src/lints/hir.rs
@@ -11,6 +11,23 @@ use crate::linter::hir::declare_hir_lints;
 
 use super::lint;
 
+// Read Me:
+//  To add a new lint add a new tuple to this structure. The tuple has four elements:
+//  `(lint_name, default_lint_level, message, help)`
+//
+//  where:
+//   lint_name: Name of the lint.
+//   default_lint_level: Default level for the lint, can be overriden by the user in qsharp.json.
+//   message: Message shown in the editor when hovering over the squiggle generated by the lint.
+//   help: A user friendly message explaining how to fix the lint.
+//
+//  Then, add an `impl lint_name` block adding the lint logic.
+//
+//  After adding a lint you need to go language_service/code_action.rs and add a Quickfix
+//  for the newly added lint (or opt out of the Quickfix) in the match statement in that file.
+//
+//  For more details on how to add a lint, please refer to the crate-level documentation
+//  in qsc_linter/lib.rs.
 declare_hir_lints! {
     (NeedlessOperation, LintLevel::Allow, "operation does not contain any quantum operations", "this callable can be declared as a function instead")
 }