Timeline for Documentation should use industry-standard solutions for collaboration [closed]
Current License: CC BY-SA 3.0
48 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Oct 4, 2018 at 2:14 | history | closed |
pnuts Dijkgraaf peterh Stephen RauchMod Nissa |
Not suitable for this site | |
Oct 4, 2018 at 1:00 | review | Close votes | |||
Oct 4, 2018 at 2:14 | |||||
Jul 22, 2016 at 14:56 | history | edited | Bartek Banachewicz | CC BY-SA 3.0 |
added 565 characters in body
|
Jul 22, 2016 at 14:44 | history | edited | Robert HarveyMod | CC BY-SA 3.0 |
deleted 6 characters in body
|
Jul 22, 2016 at 14:36 | comment | added | Robert Harvey Mod | To a large extent, code is its own documentation. I don't agree with those who say that code is completely self-documenting, but none of that is the kind of documentation we're describing here. | |
Jul 22, 2016 at 14:32 | comment | added | Bartek Banachewicz | @RobertHarvey I've just noticed your statement "Documentation is not software development.". As someone with your experience, I find it strange that you'd say that. I consider writing documentation for the code I write very much a part of its development process, and I am sure a lot of people agree. | |
Jul 22, 2016 at 12:52 | history | edited | Bartek Banachewicz | CC BY-SA 3.0 |
added 330 characters in body
|
Jul 21, 2016 at 17:45 | comment | added | davidism | 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 | |
Jul 21, 2016 at 16:56 | answer | added | PopsStaffMod | timeline score: 7 | |
Jul 21, 2016 at 16:48 | history | edited | Bartek Banachewicz | CC BY-SA 3.0 |
added 39 characters in body
|
Jul 21, 2016 at 16:47 | comment | added | bwoebi | @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) | |
Jul 21, 2016 at 16:46 | comment | added | Bartek Banachewicz | FWIW, I certainly don't expect anyone to use the CLI, I merely recommended that as an option that has very little implementation cost and could be appreciated by a lot of software developers already familiar with the underlying tool. I'll edit to point that out. | |
Jul 21, 2016 at 16:43 | comment | added | Robert Harvey Mod | @bwoebi: I'd rather put bamboo shoots under my fingernails than use the CLI. I write enough code already. Do you really expect anyone in Documentation to use a CLI? | |
Jul 21, 2016 at 16:42 | history | edited | Peter Mortensen | CC BY-SA 3.0 |
Introduced abbr. "PR".
|
Jul 21, 2016 at 16:42 | comment | added | bwoebi | @RobertHarvey well, maybe you should become a programmer then… [No offense meant… just … well… don't use SourceTree but the raw CLI?] | |
Jul 21, 2016 at 16:35 | comment | added | Robert Harvey Mod | Then find an example tool that has a workflow specifically designed for documentation, useable by mere mortals. Git is not that tool. | |
Jul 21, 2016 at 16:35 | comment | added | Bartek Banachewicz | @RobertHarvey And yet those "stupid users" have managed to collaboratively edit non-code things on github with a lot of success. | |
Jul 21, 2016 at 16:34 | comment | added | Bartek Banachewicz | @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". | |
Jul 21, 2016 at 16:34 | comment | added | Robert Harvey Mod | Think of me as the stupid user who is going to slip on the banana peel in the middle of the road. I'm your worst nightmare. Actually, I'm not your worst nightmare; your worst nightmare is the people who you're trying to foist these workflows onto that know even less than I do. | |
Jul 21, 2016 at 16:33 | comment | added | Robert Harvey Mod | That's a straw man. I never said that. | |
Jul 21, 2016 at 16:33 | comment | added | Bartek Banachewicz | @RobertHarvey can you back up the claim that git has always been a tool for software developers for software development workflows only? | |
Jul 21, 2016 at 16:32 | comment | added | Robert Harvey Mod | Irritating, I know, but still a valid point regardless. Git is primarily a tool for software developers. It's always been a tool for software developers (the word "documents" notwithstanding), and it's always been about software development workflows. Documentation is not software development. Software development is software development. | |
Jul 21, 2016 at 16:31 | comment | added | Bartek Banachewicz | @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". | |
Jul 21, 2016 at 16:31 | comment | added | Nicol Bolas | @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. | |
Jul 21, 2016 at 16:29 | comment | added | Robert Harvey Mod | Then come up with better examples. | |
Jul 21, 2016 at 16:29 | comment | added | Bartek Banachewicz | I specifically said it's not about Git. :/ | |
Jul 21, 2016 at 16:29 | comment | added | Robert Harvey Mod | Because the OP made it about Git. Like I said, propose a better workflow. | |
Jul 21, 2016 at 16:29 | comment | added | Nicol Bolas | @RobertHarvey: Why are you making this about Git? | |
Jul 21, 2016 at 16:27 | comment | added | Robert Harvey Mod | @BartekBanachewicz: Off-topic now, but I'd love to see those tools. I've been using SourceTree for a year now, and still can't figure out how to resolve merge conflicts (I've followed the instructions to launch an external diff tool). Rolling back a broken commit is a nightmare. Cloning doesn't always work. The whole thing feels like a frontend for a command-line interface, which is exactly what Git is. | |
Jul 21, 2016 at 16:25 | comment | added | Bartek Banachewicz | @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. | |
Jul 21, 2016 at 16:24 | comment | added | Robert Harvey Mod | @NicolBolas: Then come up with a workflow that works. Git is not that workflow. | |
Jul 21, 2016 at 16:24 | comment | added | Nicol Bolas | @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. | |
Jul 21, 2016 at 16:20 | comment | added | Robert Harvey Mod | I'm sorry, but I just don't see it. Stack Exchange is more than just software developers, and if there's any hope of Documentation being usable anywhere else on the network, you can't expect people to learn Git workflow to use it. Git workflow is hard enough for software developers to figure out. | |
Jul 21, 2016 at 16:16 | comment | added | Bartek Banachewicz | @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. | |
Jul 21, 2016 at 16:16 | answer | added | Nicol Bolas | timeline score: -3 | |
Jul 21, 2016 at 16:15 | comment | added | Robert Harvey Mod | I would not enjoy a document system that has workflow in any way resembling Git. Why would you need things like branching and fast-forward whatever? | |
Jul 21, 2016 at 16:14 | comment | added | Konrad Rudolph | 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. | |
Jul 21, 2016 at 16:14 | comment | added | Bartek Banachewicz | @RobertHarvey I think treating Git or Mercurial or Perforce "code" management systems isn't really being fair. Especially with the latter, which is used routinely to store assets. And git has official LFS extension since some time that's specifically meant for binaries. I provided git and github examples simply because they're abundant and I think, most popular. And again, GitHub is a great example of wrapping git and presenting a web interface that works. You can actually access github content over e.g. SVN as well. | |
Jul 21, 2016 at 16:13 | comment | added | davidism | @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. | |
Jul 21, 2016 at 16:11 | comment | added | davidism | @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. | |
Jul 21, 2016 at 16:07 | comment | added | Robert Harvey Mod | Whether you think you're endorsing Git or not, your examples are all Git-specific. Git is not an industry standard; it is a defacto one (if it is even that), and I gotta be honest: Git's shortcomings give me pause. I think there's a lot of room for improvement in Git, so I'm not convinced that basing a documentation system on its principles (or any other code management system, for that matter) makes any sense at all. | |
Jul 21, 2016 at 16:06 | comment | added | Pekka | 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. | |
Jul 21, 2016 at 16:04 | comment | added | Bartek Banachewicz | 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. | |
Jul 21, 2016 at 16:03 | history | edited | Bartek Banachewicz | CC BY-SA 3.0 |
Added real-world usage
|
Jul 21, 2016 at 16:02 | history | edited | Bartek Banachewicz | CC BY-SA 3.0 |
Added real-world usage
|
Jul 21, 2016 at 15:58 | history | edited | TylerH | CC BY-SA 3.0 |
added 5 characters in body
|
Jul 21, 2016 at 15:56 | comment | added | davidism | Given that the majority of the open source industry has been storing and updating docs using version control for ages, this seems obvious. | |
Jul 21, 2016 at 15:53 | history | asked | Bartek Banachewicz | CC BY-SA 3.0 |