Installation/setup instructions in README

[cchantep]

First, thanks for this plugin.

It would be nice to have the instructions to install/setup it directly in the README (with latest version and what to be added in a SBT build), like that.

[dwijnand]

I think the reasoning for having those details in the wiki page (which is linked at https://github.com/typesafehub/migration-manager#usage) is so that those details can be changed after a tag is cut.

[SethTisue]

in general, I think wikis for documentation are a failed experiment (not just in this repo, but basically everywhere) and I would welcome a pull request that relocated the entire contents of the wiki into a doc directory, and then we could shut down the wiki

[dwijnand]

wikis for documentation are a failed experiment

I'd be interested to understand why you think so.

[SethTisue]

I read a really good blog post about this sometime in the last year or so, but can't seem to find it now.

but the blog post just stated opinions and arguments that I had already basically arrived at on my own, from direct experience and observation

the main arguments I would make are:

• empirically, in a decade or so of experience with this now in the open source world generally: wikis nearly always rot, docs in the main repo have a fighting chance of staying up to date
• but why? two of the big reasons:
  • when you edit a wiki, there is no pull request process you have to go through; your change goes up immediately. in some contexts (e.g. Wikipedia articles about minor Star Wars characters), this is encouraging for outside contributors. for technical documents, it is strongly discouraging for outside contributors because vanishingly few outside contributors are sufficiently confident that their changes will be exactly right and not need expert review, so they don't make them at all
  • if the code and the wiki are separate, there's no smooth process by which a change to the code and a change to the documentation can be paired. whereas if code and wiki are in the same repo, feedback to a PR to the code can always be accompanied with "can you update the doc directory as part of this, please?"
• software is versioned and has branches, the wiki does not. so it's never clear what version of the software the stuff in the wiki documents

there's probably more to say about this but those are the main points that come to mind.

[SethTisue]

the only counterargument I find convincing is the one about improving the docs without having to cut a new version. but in the big picture, I think the important is dwarfed by our long, near-universal experience with rotted, neglected, ignored wikis.

[jvican]

@SethTisue A wiki does indeed have a git repository, that you can revision and host as you wish. You can add it to your project and people can make PRs to it. This is what I do in sbt-release-early.

Also, I'd like to note that my experience with open wikis so far is excellent. I'm getting really good doc contributions from random users. They just make the changes and don't go through the ordinary PR worfklow just to fix a typo/restructure a sentence.

[jvican]

The only valid issue I've seen so far in wikis is that they are not searchable. I contacted GitHub some months ago to see if they would change it, they told me they would look into it.

[cchantep]

Still "if the code and the wiki are separate, there's no smooth process by which a change to the code and a change to the documentation can be paired"

[jvican]

Most of Seth's points do not count at the very same moment a wiki has a repo.

Pairing docs and code can be good and bad. What's bad? In big projects, handling doc and code PRs in one repository can be exhausting. If you want to pair changes to code and docs, you can use cross-links with GitHub and enforce that there's always such a link for non-trivial changes in the CONTRIBUTING guide.

Note that most important projects do not keep the docs in the same repository than the code ("docs and code are not paired"), they usually have a repository with all the styling for their website (see scala/scala, sbt/sbt, etc). I think this is the same case for other important projects in other communities.

[SethTisue]

To be clear, I do already know that a GitHub wiki is itself a git repo. My thinking on this subject is not based on ignorance of that fact, not at all.

It's a git repo, but it's not a git repo you can make a pull request to.

[SethTisue]

not sure if this is the blog post, but: http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation (thanks @dwijnand for locating it)

tl;dr: people don't seem to trust Wiki content, nor explore it. They're also more nervous about editing Wiki content. Files imply: this is officially part of the project, and people feel comfortable sending a PR

[SethTisue]

I already covered some of the arguments in the blog post above, but I left out a major one, which is the argument from the consumption side. people don't trust stuff they see in wikis, and they're right not to trust it, given the neglected state nearly every wiki in the software world is in.

[jvican]

@SethTisue That is true 😄. But my wiki is perfect!

Now seriously, I think that if wikis were improved by github (add interface for PRs), a search box were added and the name wiki was changed to kiwi or the more boring "Docs", they would be a total success. Your appreciation seems to be true because people relate to their previous experiences when they read docs from a wiki.

[dwijnand]

isaacs/github#846

[jvican]

It looks like it is already possible to send PRs to wikis. See footnote in https://github.com/Microsoft/vscode/wiki/Roadmap

[dwijnand]

It requires an external service to sync the two repositories: microsoft/vscode#5671.

[SethTisue]

PR: #213