[Docs] Add a comparison with project.el

3 files changed, 79 insertions, 0 deletions

diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc
index cd6a34f..12c91cb 100644
--- a/doc/modules/ROOT/nav.adoc
+++ b/doc/modules/ROOT/nav.adoc
@@ -4,6 +4,7 @@
 * xref:projects.adoc[Projects]
 * xref:configuration.adoc[Configuration]
 * xref:extensions.adoc[Extensions]
+* xref:projectile_vs_project.adoc[Projectile vs project.el]
 * xref:faq.adoc[FAQ]
 * xref:troubleshooting.adoc[Troubleshooting]
 * xref:contributing.adoc[Contributing]
diff --git a/doc/modules/ROOT/pages/faq.adoc b/doc/modules/ROOT/pages/faq.adoc
index 73c8122..cd566a2 100644
--- a/doc/modules/ROOT/pages/faq.adoc
+++ b/doc/modules/ROOT/pages/faq.adoc
@@ -27,6 +27,8 @@ yourselves.
 One under-appreciated advantage of Projectile is that it has way more documentation.
 Okay, that's only an advantage if you're one of those rare people who enjoy reading it.
 
+NOTE: You can find a more detailed comparison xref:projectile_vs_project.adoc[here].
+
 == Does Projectile provide any integration with `project.el`?
 
 Starting with Projectile 2.7, Projectile will plug automatically its
diff --git a/doc/modules/ROOT/pages/projectile_vs_project.adoc b/doc/modules/ROOT/pages/projectile_vs_project.adoc
new file mode 100644
index 0000000..f71d0ba
--- /dev/null
+++ b/doc/modules/ROOT/pages/projectile_vs_project.adoc
@@ -0,0 +1,76 @@
+= Projectile versus project.el
+
+NOTE: As both projects are a moving target this page might not reflect the differences between the accurately.
+
+Projectile was created at a time when Emacs didn't feature built-in project
+navigation functionality. Eventually this changed in Emacs 25 with the introduction of `project.el` and a lot of people have been asking what are the advantages of using
+Projectile over the built-in library. This section of the documentation will try to answer this question.
+
+When `project.el` was originally introduced it's feature-set was quite spartan, but it has added some new features in every Emacs release and circa 2024 it should cover the needs of most casual users. I'm guessing that Projectile inspired many features in `project.el`, and Projectile itself was inspired by tools like IntelliJ IDEA.
+
+== TLDR;
+
+If the functionality in `project.el` is good enough for you than you should probably use `project.el`.
+
+== At a glance
+
+|===
+| | Projectile | project.el
+
+| Created in
+| 2011
+| 2014.footnote:[It was introduced in Emacs 25.1.]
+
+| Supported Emacs versions
+| 25+
+| 25+.footnote:[Note that the versions bundled with older Emacsen will miss some of its modern features. `project.el` is distributed as a package as well, so you can still get some of the newer functionality on older Emacsen.]
+
+| Built-in
+| no
+| yes
+
+| Package Availability
+| MELPA, MELPA Stable, NonGNU ELPA
+| GNU ELPA
+
+| Indexing Strategies
+| 3 (`native`, `hybrid`, `alien`)
+| 1 (similar to Projectile's alien strategy)
+
+| Native Project Config
+| Yes (`.projectile`)
+| No
+
+| Built-in Project Types
+| 60+
+| n/a
+
+| Extensions
+| ~20
+| ~10
+
+| Feature-set
+| Extensive
+| Essential
+
+| Contribution Process
+| Light-weight
+| Somewhat complicated (standard for Emacs)
+|===
+
+== Projectile's Pros
+
+- Projectile targets Emacs 25, so you can get all the features even with older Emacs releases
+- Projectile has different project indexing strategies, which offer you a lot of flexibility in different situations
+- Projectile supports a lot of project types out-of-the-box (e.g. `ruby`, `Rails`, `cabal` and `dune`)
+- Projectile has a lot more features, although one can argue that some of them are rarely needed
+  - Projectile's Commander is pretty cool for project switching!
+- It's easier to contribute to Projectile, as you don't need to deal with Emacs's contributor's agreement and the `emacs-devel` mailing list
+- Projectile has more extensive documentation
+
+== Projectile's Cons
+
+- Third-party dependency, developed outside of Emacs. This is both a pro and con depending on one's perspective, but I know that many people prefer built-in packages, so I've put it under "cons".
+  - Built-in packages in theory should be maintained better (or at least for longer), as they have the Emacs team behind them.
+  - While Projectile has a rich ecosystem of extensions, over a long enough period of time likely `project.el` will take the lead.
+- Due to its larger size, one can argue that Projectile is more complex than `project.el`