34

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.

35
  • 19
    Given that the majority of the open source industry has been storing and updating docs using version control for ages, this seems obvious.
    – davidism
    Commented Jul 21, 2016 at 15:56
  • 3
    I'd like to point out that I don't want to specifically endorse Git or any other particular version control system here for the use in Documentation. Please don't make it a VCS war either. Commented Jul 21, 2016 at 16:04
  • 1
    Not saying the system doesn't have its problems, but is Git or some other VCS really the solution here? Documentation is based on Stack Overflow's editing interface, which at this point is an industry standard in itself, no? Not sure whether a simple, accessible documentation interface needs anything more.
    – Pekka
    Commented Jul 21, 2016 at 16:06
  • 7
    @RobertHarvey it works really well for all the projects I manage or contribute to. Git isn't a code management system, it's a document revision system. The fact that some documents are code isn't relevant.
    – davidism
    Commented Jul 21, 2016 at 16:11
  • 5
    @RobertHarvey I agree that full blown Git isn't the answer, but even Wikipedia has a system for managing simultaneous edits that's more useful than the current docs strategy. Although it doesn't have a concept of pending edits, so the workflow is more linear.
    – davidism
    Commented Jul 21, 2016 at 16:13
  • 3
    In the same vein (but maybe fit for another topic) it’s also ridiculous to assume that documentation should be hand-written rather than generated by tools — especially considering that for many projects, excellent machine-readable documentation (doxygen …) does already exist. I like the emphasis on examples here but this is hardly a new idea, and many excellent documentation systems already support/encourage this. Commented Jul 21, 2016 at 16:14
  • 5
    @RobertHarvey Branching is specifically important for Pull Requests. It allows multiple people to work on the same thing, in parallel, and share progress between them to be later merged into one common final version. It's not specific to code at all. Commented Jul 21, 2016 at 16:16
  • 7
    @RobertHarvey: Nobody is requiring that you use Git specifically or Git's workflow. What they want is something that actually allows collaboration on edits, which the current system utterly fails at. Git would do that, but it's not the only option. Commented Jul 21, 2016 at 16:24
  • 3
    @RobertHarvey You seem to be intentionally forgetting that there are tools which simplify working with git tremendously and aren't used just by developers. Putting aside the fact that we're talking about documentation for developers in the first place, all of non-code (or even code-related) projects on github pretty much prove you wrong on the spot. Commented Jul 21, 2016 at 16:25
  • 3
    @RobertHarvey: Why are you making this about Git? Commented Jul 21, 2016 at 16:29
  • 6
    @RobertHarvey: "Then come up with better examples." Or, you know, you could focus on the idea behind the example instead of the example itself. Like allowing collaborative editing in a way that actually works. Or whatever. The fact that Git is mentioned should not cause your brain to shut down. Commented Jul 21, 2016 at 16:31
  • 6
    @RobertHarvey I don't mean to be rude, but frankly your whole criticism of the specific examples that I've presented sounds like a projection of your problems with git. I've pointed out that people use it to edit code non-related things, and you respond with "I still can't figure out how to use it". Commented Jul 21, 2016 at 16:31
  • 6
    @RobertHarvey Then I have no idea why would you ever say anything about it, since code versioning is clearly not relevant here. Software development is software development. I proposed use of collaboration software for docs here. I'd like to hear actual criticism that's not "it's been designed and used for something else". Commented Jul 21, 2016 at 16:34
  • 2
    @RobertHarvey Uhm… perhaps? At least I personally work fine with using git (via CLI obviously) for docs… Honestly, I've never seen a GUI for git superior to the CLI. … But as the OP says, the topic isn't about this... (P.s. and you must really like bamboo shoots under my fingernails under your fingernails then :-P)
    – bwoebi
    Commented Jul 21, 2016 at 16:47
  • 4
    I tried to address the most immediate issue as a bug report here: Documentation treats edits as linear, like Q&A, but they are not
    – davidism
    Commented Jul 21, 2016 at 17:45

2 Answers 2

7

Out of everything you said, the thing that concerns me the most is "Potential problems are hand-waved and dismissed." I can't be 100% sure why you feel that way without examples, but my best guess is that we're not yet making major changes in response to the feedback we've gotten so far, or scrapping the whole project and using a VCS or some other system.

VCSes are indeed, as you say, a good, battle-tested, already-invented wheel, but allow me to look at this from another angle.

Problems can have multiple solutions. Say you're hungry. Maybe you choose to eat some pizza; maybe you choose to eat a burger. Just because a burger would be effective doesn't automatically make pizza a bad choice. The new Documentation system we have created may not be a VCS, but we think it will ultimately be able to effectively solve many of the problems facing technical documentation today. In other words, I don't see this as a "step back" because it's not a question of better-or-worse. It's simply different.

It's the very fact that this is a novel, untested system that makes us want to keep at it. We didn't just throw this together overnight. A huge amount of thinking and planning went into inventing and building Documentation, and there are reasons behind all of the major design decisions that were made. It's not just about hours and effort spent; we believe in this thing we have built.

At the same time, we expect and understand that with a huge software rollout, there will inevitably be technical bugs and human issues we didn't foresee. We also intend to learn a lot from how people use the system, and make improvements based on our new insights. That is, after all, why the thing is called a beta.

Our immediate responses will generally be to deploy bugfixes and small tweaks, and re-evaluate. Fortunately, we don't have any artificial time constraints hampering this project. We can give things more than a few hours to sink in and see how people react. We can react with "just" small-scale changes, see how they affect the system, and use that information in planning potential bigger future changes. We can give everyone an extra few hours or days to ponder why things are or aren't working as expected, and what to do about it.

There are certainly times when radically pivoting all over the place is the right choice, but I don't think the start of a large-scale beta when most people are still getting their bearings is one of them. As we're writing these posts, Documentation is less than a day old. People in some parts of the world haven't even gotten to see it yet! It may not be as good as it could be right off the bat, but we're asking you (and everyone else) to bear with us for a little while. It was always the plan that the system would get better and better as we learned from the beta. Please give it a chance for a little while longer; you might find that this ends up being pretty okay.

13
  • 11
    "I can't be 100% sure why you feel that way without examples, but my best guess is that we're not yet making major changes in response to the feedback we've gotten so far, or scrapping the whole project and using a VCS or some other system." People say that because this is how it has been with Docs.SO from its very inception. Nothing significant about the direction of Docs.SO has been driven by the community. The only suggestions that have been taken into consideration are small things. Everything else has been dismissed with a "wait and see" attitude. Commented Jul 21, 2016 at 17:02
  • 4
    And also because of the feeling we've had of shouting in the void with with feature requests in general.
    – davidism
    Commented Jul 21, 2016 at 17:02
  • 1
    @NicolBolas That's fair. I don't know if there's another way to respond to feedback along the lines of "I haven't seen it yet, but I think you should just scrap the whole thing", which is what we got sometimes, but either way - the wait is over and we're finally at the "see" part. We'll find out how this whole thing works out. It might or it might not. As Pops said, we believe in what we've got so far, but failure is always an option.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 17:07
  • @NicolBolas that... is true. If it helps, I think it was more true in the past than it will be from here on out. I'm not just saying that because you raised the point and I want to reply, it's more that we've now moved on to a new phase in the project. We absolutely love the SO community; without you, we would have nothing. But design by committee is hard, even when the committee size is as small as "part of the SO dev team." As the system matures, we'll have a better understanding of how things work in practice and where we can integrate community suggestions.
    – Pops StaffMod
    Commented Jul 21, 2016 at 17:15
  • 1
    Pops, I think the problem is the perception that the structuring of SO Q&A really hasn't changed in any fundamental way since inception. A lot of that is presented as "we're totally convinced this is The One True Way", but it's hard not to think that some improvements have been skipped not because they're bad but just because they're too much effort. And people are convinced that Documentation will follow the same appears-to-be-superficial-changes-only-to-backend approach, while it would really benefit from a complete overhaul. And that overhaul only gets more expensive the longer it waits.
    – Ben Voigt
    Commented Jul 21, 2016 at 19:57
  • @BenVoigt That's fair. Q&A was always more of a screwdriver than a multitool. I.e. it was designed to handle "I have this specific problem" well, but not worry about discussions. I've been thinking a bit in past weeks about just what you said, how we don't make a lot of big feature changes to Q&A anymore. A lot of it is that Q&A is simply a mature, more-or-less smoothly running thing now, and big new systems would be disruptive yet probably not that helpful. But that's not the case with Docs; the team's position is to be receptive to "big change" ideas (though they may still take time).
    – Pops StaffMod
    Commented Jul 21, 2016 at 20:21
  • 1
    "Problems can have multiple solutions. ..." That is the whole defense? I would have expected more arguments why the new solution is better (or at least not much worse). Some ideas how to efficiently solve edit conflicts for example. What worries me most is the lack of public ideas on tackling the core problems of the chosen approach. Commented Jul 22, 2016 at 13:01
  • Here's an example.
    – Cerbrus
    Commented Jul 22, 2016 at 13:17
  • 4
    @Trilarion there actually was a lot of "here's the thought process behind why X was designed this way" writing posted during the private beta. We're working on migrating those posts over to meta now that private beta is over, it'll just take the standard 6-8 weeks. Sorry for the delay!
    – Pops StaffMod
    Commented Jul 22, 2016 at 14:08
  • @Pops Thanks for copying. The successful collaborative editing is surely the heart of the whole thing. I'm curious what ideas there have been to solve problems like edit conflicts or duplication of content or categorization. :) Commented Jul 22, 2016 at 14:27
  • @Pops Then I will wait with closing this question until those posts actually appear and some factual reasoning is brought to the table as to why using an existing tool like Microsoft and others did was not a good option here. If anything, it will certainly bring a lot of educational value for making such decisions. Commented Jul 22, 2016 at 15:00
  • @BartekBanachewicz you won't be finding much of that in the posts I described. As far as I know, our approach was more along the lines of "The state of technical documentation could be better. Let's come up with a solution. Don't feel limited or restricted by existing solutions or preconceived notions about what our solution has to look like; instead, work it out from basic principles." And many months later, it so happened that what we came up with ended up not being substantially similar to a VCS.
    – Pops StaffMod
    Commented Jul 22, 2016 at 15:19
  • 2
    @Pops Actually what you came up is a form of a VCS. It tracks things and changes to them. Except it's a proprietary in-house solution instead of an open one, which supposedly should be tailored better to what we're gonna create here. I get that part; I eagerly await to see it actually perform better than solutions based on existing VCS systems. Commented Jul 22, 2016 at 15:57
-3

If Docs.SO were a system where a small cloister of people edit pages, pass changesets around to each other, and after reviewing everything pushes it out to a webpage, then direct access to a back-end VCS would make sense. But that's not what's being built here.

The ability to fork documentation, make radical realterations & restructurings, and then send it back as a pull request is not a useful thing for the kind of collaborative work that's being done here. Indeed, it's negatively useful; we don't want a single person to be able to do that sort of thing. After all, it only takes a few people to accept a change, and then suddenly everything is different.

Ultimately, I don't see what access to the back-end storage of the system would permit. As it stands now, we can get better inter-person collaboration simply by allowing people to fork each others' drafts. And we kinda have that now; you can reject an edit request, then modify it yourself and re-submit it. We just need it to be more formalized.

14
  • 7
    I think you are completely wrong in this (i.e. PRs and radical restructuring is tremendously useful here). But even if you were right, the answer would be something like the collaborative editing in Google Docs; not the current solution here. Commented Jul 21, 2016 at 16:17
  • 1
    Something like google docs is too realtime I think. In worst case you have editwars and nobody from outside really sees who's at fault.
    – bwoebi
    Commented Jul 21, 2016 at 16:19
  • 3
    "We just need to be more formalized" - but that's one thing that you get for free with a VCS. And I absolutely don't understand the remark about a "small cloister" of people. GLTF is managed on github and it works great. There are projects on GH with thousands of contributors to a single project and it still works well. The backend access was merely a "nice-to-have". Commented Jul 21, 2016 at 16:20
  • @KonradRudolph: "the answer would be something like the collaborative editing in Google Docs; not the current solution here." Is that not what I suggested in the last paragraph? An improved system for doing things like that? Commented Jul 21, 2016 at 16:20
  • @bwoebi That's the kind of edit-war that I would love to watch in real time. People fighting over formatting or US vs. British spellings - that would be hilarious.
    – Mysticial
    Commented Jul 21, 2016 at 16:20
  • 1
    @BartekBanachewicz: "GLTF is managed on github and it works great." Because there is a small cloister of people who own it. They decide what goes in and what does not. It's not everyone being equal the way Docs.SO wants to work. Commented Jul 21, 2016 at 16:21
  • @Mysticial It's hilarious, I totally agree, but perhaps SO docs are not the place to do that... :-D (But just perhaps :-P)
    – bwoebi
    Commented Jul 21, 2016 at 16:21
  • 1
    @NicolBolas There have already been proposals thrown around that tag badges or rep should dictate control over tag docs. That's not really different from contributor lists. Besides, open source projects still have PRs that are voted on by community, which mean pretty much everyone interested. Having a few people that actually approve the commit isn't the real issue here, and you could replace them with automatic voting altogether anyway. Commented Jul 21, 2016 at 16:23
  • @BartekBanachewicz: "There have already been proposals thrown around that tag badges or rep should dictate control over tag docs." But since those proposals have not happened, nor has there been any suggestion that they will happen, it's irrelevant. As it stands right now, Docs.SO is built on a model of all editors being essentially equal. Commented Jul 21, 2016 at 16:27
  • 1
    @NicolBolas then I believe the solution with voting for PR merge is equivalent to voting for edit approval. Commented Jul 21, 2016 at 16:39
  • @BartekBanachewicz: "then I believe the solution with voting for PR merge is equivalent to voting for edit approval." ... how? It takes 2 people to approve an edit. Presumably, it takes far more than that to get a pull request approved. And even then, someone must certify the vote. Commented Jul 21, 2016 at 16:40
  • 1
    @NicolBolas Why do you assume that "it takes far more than that to get a pull request approved"? I am not saying that SO should literally take github code or call edits "pull requests". PRs aren't built-in into git, neither is the voting mechanism or their approval. Git merely provides a platform to take changes and manage them. Whatever mechanism you build on top is entirely up to you, and you could literally rebuild current approval mechanism simply utilizing git to merge changes and warn about conflicts (instead of that huge red wall of "others are editing"). Commented Jul 21, 2016 at 16:54
  • @BartekBanachewicz: And if you did that... what would it change? You'd still have a "huge red wall" because that's built into the interface, not the back-end. Whether those changes are Git revisions or some other database thing, they still would show up in the interface, and you'd still have to deal with it. The back-end is not Docs.SO's current problem. Commented Jul 21, 2016 at 16:57
  • 6
    Nicol, while I agree with you that editors don't need direct access to a VCS backend, I think you're totally wrong when you say the complex merging scenarios that modern VCSes support aren't useful for Documentation.SO You admit that better forking/branching is needed, but that's pretty useless until you have a way to merge/reintegrate from multiple branches as well, along with some voting on which parts should be merged, and then you basically have built a VCS.
    – Ben Voigt
    Commented Jul 21, 2016 at 19:52

Not the answer you're looking for? Browse other questions tagged .