Refactor!

CONTRIBUTING.md

@@ -1,35 +1,52 @@
 # Contributing guide
 
-The two main ways to help the project are reporting and fixing bugs.
+You can contribute to tree-sitter-julia by reporting or fixing bugs.
 
 
 ## Report bugs
 
-To report a bug, you can file an [issue on gitHub](https://github.com/tree-sitter/tree-sitter-julia/issues).
-If possible, the issue should include an brief explanation of the bug, the expected behavior, and a minimal reproducible example.
+To report a bug, you can file an [issue on GitHub](https://github.com/tree-sitter/tree-sitter-julia/issues).
+Follow the bug report template to ensure the issue includes a brief explanation of the bug,
+the expected behavior, and a minimal reproducible example.
 
-If your text editor isn't highlighting code correctly, the error might be in the editor or in the parser.
-The best way to check if it's an error in the parser is to read the generated syntax tree of the erroneously highlighted code.
-Some editors can display the syntax tree of a text file.
-For example, Neovim has the [`:InspectTree`](https://neovim.io/doc/user/treesitter.html#vim.treesitter.inspect_tree()) command.
+If your text editor isn't highlighting code correctly, the error might be in the the parser or the queries.
+If the syntax tree has `ERROR` nodes for valid Julia programs, the error is probably on the parser and
+you should file an issue in this repository. Remember that we don't control the version of the parser used by editors,
+so some issues might be due to your editor using an outdated parser.
+
+Otherwise, if the syntax tree appears to be correct, the issue might be with the queries used by your editor.
+We keep a minimal set of queries in this repository, but most editors include their own queries.
+If there's an issue with queries you should _file an issue in your editor or plugin's corresponding issue tracker._
 
-If the syntax tree has `ERROR` nodes for valid Julia programs, then you should file an issue here.
-Otherwise, if the syntax tree appears to be correct, the issue might be with the queries used by the text editor.
-In that case, you can file an issue in the corresponding issue tracker.
+The easiest way to check if there's an error in the parser is to read the generated syntax tree of the erroneously highlighted code.
+Some editors can display the syntax tree of a text file directly.
+For example, Neovim has the [`:InspectTree`](https://neovim.io/doc/user/treesitter.html#vim.treesitter.inspect_tree()) command.
 
 
 ## Build and develop
 
 tree-sitter-julia follows the usual structure of a tree-sitter project.
-To get started, you should read the [Creating parsers](https://tree-sitter.github.io/tree-sitter/creating-parsers) section of the tree-sitter docs.
+- To get started, you should read the [Creating Parsers](https://tree-sitter.github.io/tree-sitter/creating-parsers) section of the tree-sitter docs.
+- Every bug fix or new feature should include tests. This helps us document supported syntax, check edge cases, and avoid regressions.
+- Note that the grammar is mostly done feature-wise, but optimizations in build size and compilation speed are very welcome.
+
+
+## Guidelines for writing queries
+
+The queries in this repository should follow the following rules:
 
-The grammar is mostly done feature-wise, but optimizations in build size and compilation speed are very welcome.
-Currently the grammar takes a while to compile (about 1 minute).
+- No highlighting is better than ambiguous highlighting.
+  If syntax highlighting is excessive or _wrong,_ it loses its value.
+- Only public names defined in `Core` should be highlighted as `builtin`.
+  Julia `Base` is huge, and highlighting everything in it has diminishing returns.
+- Captures mostly follow [Neovim's naming conventions](https://neovim.io/doc/user/treesitter.html#treesitter-highlight-groups),
+  since they're well documented and widely used.
+  Adapting the captures to work with other editors usually requires a few small changes.
 
-Every new feature or bug fix should include tests. This helps us document supported syntax, check edge cases, and avoid regressions.
 
+# Editor specific details
 
-## Neovim specific details
+## Neovim
 
 The Julia queries used in Neovim are in the nvim-treesitter repository:
 - [Queries](https://github.com/nvim-treesitter/nvim-treesitter/tree/master/queries/julia)

README.md

@@ -15,23 +15,10 @@ A [tree-sitter](https://github.com/tree-sitter/tree-sitter) parser for [Julia](h
 - [Julia ASTs documentation](https://docs.julialang.org/en/v1/devdocs/ast/)
 - [JuliaSyntax.jl](https://julialang.github.io/JuliaSyntax.jl/dev/)
 
-## Guidelines for writing queries
-
-- No highlighting is better than ambiguous highlighting.
-  If syntax highlighting is excessive or _wrong,_ it loses its value.
-
-- Only public names defined in `Core` should be highlighted as `builtin`.
-  Julia `Base` is huge, and highlighting everything in it has diminishing returns.
-
-- Captures mostly follow [Neovim's naming conventions](https://neovim.io/doc/user/treesitter.html#treesitter-highlight-groups),
-  since they're well documented and widely used.
-  Adapting the captures to work with other editors usually requires a few small changes.
-
 [ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/tree-sitter-julia/ci.yml?logo=github&label=CI
 [discord]: https://img.shields.io/discord/1063097320771698699?logo=discord&label=discord
 [matrix]: https://img.shields.io/matrix/tree-sitter-chat%3Amatrix.org?logo=matrix&label=matrix
 [npm]: https://img.shields.io/npm/v/tree-sitter-julia?logo=npm
 [crates]: https://img.shields.io/crates/v/tree-sitter-julia?logo=rust
 [pypi]: https://img.shields.io/pypi/v/tree-sitter-julia?logo=pypi&logoColor=ffd242
 
-