diff --git a/crates/hir_def/src/diagnostics.rs b/crates/hir_def/src/diagnostics.rs
index c71266dc0913..ab3f059cef67 100644
--- a/crates/hir_def/src/diagnostics.rs
+++ b/crates/hir_def/src/diagnostics.rs
@@ -133,6 +133,10 @@ impl Diagnostic for InactiveCode {
 // This diagnostic is shown when a procedural macro can not be found. This usually means that
 // procedural macro support is simply disabled (and hence is only a weak hint instead of an error),
 // but can also indicate project setup problems.
+//
+// If you are seeing a lot of "proc macro not expanded" warnings, you can add this option to the
+// `rust-analyzer.diagnostics.disabled` list to prevent them from showing. Alternatively you can
+// enable support for procedural macros (see `rust-analyzer.procMacro.enable`).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct UnresolvedProcMacro {
     pub file: HirFileId,
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 75445a02e567..266baffa177c 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -18,6 +18,9 @@ The LSP allows various code editors, like VS Code, Emacs or Vim, to implement se
 [.lead]
 To improve this document, send a pull request: +
 https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[https://github.com/rust-analyzer/.../manual.adoc]
+
+The manual is written in https://asciidoc.org[AsciiDoc] and includes some extra files which are generated from the source code. Run `cargo test` and `cargo xtask codegen` to create these and then `asciidoctor manual.adoc` to create an HTML copy.
+
 ====
 
 If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.