Updated doc

Author: dantleech

doc/README.md

@@ -20,10 +20,9 @@ power can only be utilized through its RPC protocol. It ships with support for V
 would not involve a huge amount of effort to support other editors such as
 [GNU Emacs](https://www.gnu.org/s/emacs/).
 
-Phpactor is a bleeding-edge product, it is far from being perfect, it probably
-never will be. It's a work in progress. But, I have been using it extensively
-in my daily work and haven't felt especially compelled to add new features for
-some months.
+Phpactor is currently bleeding-edge software, none of it is perfect, but most
+of the features will get you most if not all of the way to where you want to
+go.
 
 Packages
 --------

doc/history.md

@@ -14,11 +14,12 @@ my editor grew more and more as IDEs such as Jetbrains
 [PhpStorm](https://www.jetbrains.com/phpstorm/) and Idea platforms offered more
 and more great features.
 
-VIM is a great text editor, but it is essentially dumb. Nevertheless, I still
-_felt_ that I could program faster and more efficiently in VIM running in
-[Tmux](https://github.com/tmux/tmux/wiki) sessions in a minimal tiling desktop
-environment such as [I3](https://i3wm.org/). I became extremely good at
-typing, and developed muscle memory for class constructors and properties.
+VIM is a great text editor, but it is essentially ignorant of the meaning of
+code. Nevertheless, I still _felt_ that I could program faster and more
+efficiently in VIM running in [Tmux](https://github.com/tmux/tmux/wiki)
+sessions in a minimal tiling desktop environment such as
+[I3](https://i3wm.org/). I became extremely good at typing, and developed
+muscle memory for class constructors and properties.
 
 Not having these refactoring tools however also meant that the lack of them would
 have a direct influence on the quality of my code and architecture (if would
@@ -27,15 +28,16 @@ that).
 
 Of course there were a multitude of ways to mitigate this lack of functionality
 and for some time I had, for example, been using ctags completion (basically
-regexy dumb completion) and code snippet generators, but a real contextually
-aware code completion and refactoring tool for PHP was simply not available.
+regexy "dumb" completion) and code snippet generators, but a real
+contextually aware code completion and refactoring tool for PHP was simply not
+available.
 
 I was excited to find out about projects like
 [Padawan](https://github.com/padawan-php/padawan.php) and other similar
 efforts, but they all seemed either unstable or sub-optimal (at the time at
 least) and after a while I thought "how hard can it be"? So in 2014 I wrote the
-first version of Phpactor. It was terrible. 1 year later I wrote another,
-again, it sucked. The ongoing third effort is what we have here today.
+first version of Phpactor. It was failed. 1 year later I wrote another, it
+sucked. The ongoing third effort is what we have here today.
 
 One of the things that made Phpactor possible was the Microsoft [Tolerant PHP
 parser](https://github.com/Microsoft/tolerant-php-parser) (TPP), a great library
@@ -49,8 +51,8 @@ other projects and they didn't mature.
 Initially I also used the [Nickic PHP
 parser](https://github.com/nikic/PHP-Parser) - the defacto PHP parser in the
 PHP world today, but I found the TPP much easier to work with as it
-provides tree-traversal (and was matched to Phpactor's use case - I believe
-essentially created to support the [VS
+provides node tree-traversal (and was matched to Phpactor's use case - I _believe_
+it was essentially created to support the [VS
 Code](https://en.wikipedia.org/wiki/Visual_Studio_Code) eco-system and
 contribute to Microsoft's efforts to _take control of the market_).
 
@@ -68,33 +70,32 @@ domain of Phpactor and is subservient to its needs.
 Why not PHP Language Server?
 ----------------------------
 
-No reason - PHP language server is great. Well, there are some differentiators:
-
-- **Phpactor does not index anything**: This is both good and bad, good
-  because it is fast (depending on the operation), doesn't suffer from memory
-  issues and has no start-up penalty. It uses short lived processes, which is
-  what PHP is good at. We locate files quickly by depending on
-  the [Composer](https://getcomposer.org) autoloader. Bad because
-  it cannot discover non-autoloadable classes or (at time of writing) provide
-  completion for functions in the wild. Phpactor does not work well without Composer.
-- **Phpactor is also a refactoring tool**: Phpactor provides [refactorings](refactorings.md) and
-  procedures to help you code faster and more accurately (such as complete
-  constructor, generate method, implement contracts etc).
+No reason - PHP language server is great. But there are some differentiators:
+
+- **Phpactor is realtime**: It does not index anything. This is both good and
+  bad, good because it is fast (depending on the operation), doesn't suffer
+  from memory issues and has no start-up penalty. It uses short lived
+  processes, which is what PHP is classically good at. We locate files quickly
+  by depending on the [Composer](https://getcomposer.org) autoloader. Bad
+  because it cannot discover non-autoloadable classes or (at time of writing)
+  provide completion for functions in the wild. Phpactor still works without 
+  composer by traversing your project tree, but it's speed is then relative to
+  project size.
+- **Phpactor is also a refactoring tool**: Phpactor provides
+  [refactorings](refactorings.md) and procedures to help you code faster and
+  more accurately (such as complete constructor, generate method, implement
+  contracts etc).
 - **Phpactor ships with a VIM plugin**: Phpactor ships with a [VIM plugin](vim-plugin.md).
 
-… and competition for the eco-system right? "Competing" products allow more
-independent vectors of discovery.
-
 Why not Language Server Protocol?
 ---------------------------------
 
 The [Language Server
 Protocol](https://github.com/Microsoft/language-server-protocol) defines a
 standard protocol for an editor to talk to a language server. Phpactor is
-essentially a language server.
-
-Phpactor does not currently support the Language Server protocol, but it does
-implement its own [RPC Protocol](rpc.md). It is not currently aligned with the LSP.
+fills the role of a language server, but it's essentially a PHP script.
 
-In the future it may happen that Phpactor will implement LSP, or maybe it will
-be made redundant by the PHP Language Server `¯\_(ツ)_/¯`.
+Phpactor currently implements its own [RPC Protocol](rpc.md), this at least
+gives it flexibility. But it would be great to eventually either replace this
+with LSP or provide an LSP interface and therefore be a generic backend for
+all editors with LSP support.