The documentation project was introduced to us as a way to revolutionize documentation. While the details of how that would work are still rather muddy, I'd like to express my concerns about the underlying mechanics of the platform.
First of all, the programming community has been trying to solve collaborative editing of things, most importantly code, for quite some time already. That's how VCSs were born, and then their distributed variants. Then, when that became open to the world, a way to accept changes from everyone and not just established contributors became necessary, and thus GitHub pull requests (PRs) appeared.
Both of those have been used and battle-tested in the industry, utilized by millions of people for the weirdest things possible. We learned that Git can version other things than code, we learned how important improving the PRs is. It works, it's thriving, and it's constantly improving.
As a matter of fact, a lot of documentation is built directly from code comments, versioned together with the code. This is another well-known and used practice that ensures consistency of documentation and allows for it to be edited with the same tools and means. (thanks @davidism)
Now, when I look at Documentation beta, released in 2016, I see a huge step back. Sure you can say that it's a beta; beta features can be unstable and quirky. What's unlikely to change out of beta, though, is the core mechanism for the whole platform, and that's really resembling systems years back.
Collaboration on the same topic from multiple people is virtually impossible. Potential problems are hand-waved and dismissed. New topic suggestions cannot be edited, and if they are retracted, all comments disappear from them. Imagine this happened with your GitHub pull request.
Now, I understand you took a huge challenge. But huge challenges need not be taken on alone and from scratch! You have a lot of existing tools, knowledge, and solutions to take from and incorporate, and I believe it would make life easier for everyone. Contributors would get a better platform, and the platform would be able to solve a lot of posed problems with relative ease; in fact, most of them wouldn't even appear in the first place.
To sum up:
- The underlying mechanism of docs should use some version control system that allows easy merging and creating change proposals
- The change proposals should be branches that can be subsequently edited.
- The comments and discussions on those should dynamically update when the proposal is updated.
- Ideally, for very little effort a direct interface to the underlying versioning mechanism could be exposed as an addition to the web interface, so that people already familiar with the system could use it directly.
Pretty much every single thing from there has been implemented by every major source control solution. Don't reinvent wheels.
As an another example, ReadTheDocs.org has a following statement on their main page:
You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar
Version Control and Documentation go and should go together, when possible.
Yet another example (thanks @Shog9), new Microsoft Docs uses GitHub as its storage mechanism.
All documentation on docs.microsoft.com is open sourced and designed to allow community contributions. (...) Every article has an Edit button (shown below) that takes you to the source Markdown file in GitHub where you can easily submit a pull request to fix or improve content.
As you can see, Microsoft also recognized that you don't need to use advanced CLI access to reap VCS benefits.