move documentation from wiki to git

[blairconrad]

Having the docs in the wiki is convenient, and allows for convenient updates by anyone in the world, but introduces problems keeping the documentation synchronized with the code. This was most apparent during the current long-running 2.0.0 release cycle, but I've noticed it other times as well.
If we moved the documentation into the code, and used something like Read the Docs to host our documentation, we'd be able to

1. Update the documentation at the same time the code was changing. Ideally whoever was contributing a fix or enhancement would also update the documentation, but we could do so in a superseding PR if needed. This would ease our cognitive load, and help reduce the work needed to release a new version - no more scrambling at the last minute to make sure the docs are correct.
2. Make available different versions of the documentation, for those stuck using older versions of the library
3. Not have to worry so much about footnotes or the fancy "[Version 1.x | Version 2.x]" selectors on pages.

I'd be inclined to put product documentation in the source. You know, things that relate directly to using FakeItEasy and may change release by release.
I think keeping the contributor / owner docs in the wiki makes more sense.

Changes I'd like to make before publishing Please push back if there's anything that doesn't make sense

• tidy everything up as best I can
• create separate branches for working on the 1.25.3 and 2.0 versions
• in the 1.25.3 branch, move all the "in 1.x" topics to replace their "unversioned" twin (see Raising Events for a sample, if you don't know what I'm talking about)
• remove from the 2.0.0 documentation all the notes that refer to how things changed between 1.x versions. Like the footnotes on the Bootstrapper page. We'd be making the 2.0.0 documents a clean break from the 1.x version. The 1.25.3 documentation could retain these
• reference to "Running multithreaded unit tests with FakeItEasy" from the 2.0.0 version of the "External Resources" page. We shouldn't need it.
• remove "Slow startup time" from the 2.0.0 documentation. The issues we knew about have been addressed, and there have been no complaints for a long time. With no reason to assume that this will be a problem again, why devote space to it?
• remove "Upgrading from older versions" from the 2.0.0 documentation? It handles one very specific task that will need to be done to upgrade from an old version, ignoring nearly everything else.
• send PRs, to universal acclaim (1.25.3: Put 1.25.3 docs in the repo #627, 2.0: Put 2.0.0 docs in the repo #628)
• add better styling to the 2.0 version, as was included in 1.25.3 (Improve documentation code styling #635)
• update ReadTheDocs project. I suggest having "stable" be the default view, but making sure we also build the "latest" docs.
• remove "Changes in 2.0" from the documentation, putting in release notes ( Remove Changes in 2.0 topic #636)
• remove content from wiki, pointing at ReadTheDocs
• make issue for web site, to point at ReadTheDocs (Have "Documentation" point to ReadsTheDocs docs fakeiteasy.github.io#28)

[blairconrad]

I downloaded the wiki pages and did a very small amount of styling.
With nearly no effort expended, I have teasers!

[blairconrad]

as you can see, the wiki-style links ([[implicit creation options…]]) would need fixing, but I'm more than happy to put that kind of effort in.

[thomaslevesque]

What do you think?

I completely agree with your suggestion

I downloaded the wiki pages and did a very small amount of styling.
With nearly no effort expended, I have teasers!

Looks great! 👍

[blairconrad]

w00t!

I think there may also be benefit in moving the release notes to committed files, but one issue at a time.

And now, just to make things more interesting, if @adamralph signs onto the overall idea of moving the docs, I think it would be good to have this done in time for the 2.0.0 release. That way we can say all 2.x+ documentation is in readthedocs or whatever.

Oh, there's the lingering concern of what to do with the 1.x docs. We could leave them in the wiki, with a warning. I'm not sure how to move them to readthedocs without adding a commit that's tagged with a 1.x.y label… I may dig for more information on alternatives.

[thomaslevesque]

I think it would be good to have this done in time for the 2.0.0 release

Sounds good to me

Oh, there's the lingering concern of what to do with the 1.x docs. We could leave them in the wiki, with a warning. I'm not sure how to move them to readthedocs without adding a commit that's tagged with a 1.x.y label… I may dig for more information on alternatives.

We could just add the 1.x documentation in a new 1.x branch (based on the last 1.x.y tag)

[blairconrad]

My thought as well, but wasn't sure how it would sit on everyone's "ideal vs. pragmatic" scale.

[thomaslevesque]

My thought as well, but wasn't sure how it would sit on everyone's "ideal vs. pragmatic" scale.

Well, I'd say it's both pragmatic and ideal 😉 (at least I can't see any obvious drawback)

[blairconrad]

If we want the docs to show up as "1.25.3", I think we'd need to tag with 1.25.3, and that tag already exists. If we moved it, it would no longer correspond exactly to the state of the repo that we released build 1.25.3 from.

The parts that matter would be the same. Just not everything.

[adamralph]

I love it. I'm also a huge fan of https://readthedocs.org/ and I already played with it for FIE - https://readthedocs.org/projects/fakeiteasy/

If the 1.x docs are problematic because of the tag, then I suggest we leave them where they are in the wiki and start with 2.0 in readthedocs.

[adamralph]

Actually, for 1.x we can use the branching approach. We just create a support-1 branch at the current 1.25.3 commit, add a docs-only commit to it and then just move the tag.

[thomaslevesque]

If the 1.x docs are problematic because of the tag

Maybe I'm missing something obvious, but I don't really understand what the problem is. Does it have something to do with how ReadTheDocs works?

then I suggest we leave them where they are in the wiki and start with 2.0 in readthedocs.

If we leave the 1.x docs in the wiki, I'm worried people will often look in the wrong place when looking for the docs...

[adamralph]

@blairconrad @thomaslevesque if you give me your account names for readthedocs then I'll make you co-owners of the project.

[adamralph]

@thomaslevesque

Maybe I'm missing something obvious, but I don't really understand what the problem is. Does it have something to do with how ReadTheDocs works?

Yes, readthedocs generates documents by building from tags in the GitHub repo, so if we want docs versioned 1.25.3 then they need to be built from that tag in the repo. However, the commit which has that tag has no docs content. So, we'd need to branch off from that tag (I suggest a "support-1" branch) add a commit to add the docs content and then move the tag to that commit, then rebuild the docs in readthedocs.

If we leave the 1.x docs in the wiki, I'm worried people will often look in the wrong place when looking for the docs...

Agreed, I'm 👍 to go with the hacked tag approach.

[thomaslevesque]

Ah, I see.

Moving tags is probably not a good habit, but in this case I think it's ok, as long as we're not touching the code.

[thomaslevesque]

@blairconrad @thomaslevesque if you give me your account names for readthedocs then I'll make you co-owners of the project.

I just created mine: thomaslevesque

(I expected readthedocs to support GitHub OAuth login, but sadly it doesn't)

[adamralph]

as long as we're not touching the code

That's the key to the hack. 😄

We have to be very careful that the commit only adds the docs content.

[blairconrad]

@blairconrad @thomaslevesque if you give me your account names for readthedocs then I'll make you co-owners of the project.

blairconrad!

Um. Without the exclamation point. I was excited.

Like @thomaslevesque, I was surprised at having to "create an account". I was griping about it to a coworker.

Actually, for 1.x we can use the branching approach. We just create a support-1 branch at the current 1.25.3 commit, add a docs-only commit to it and then just move the tag.

Oh, good. That was my thought. I feared it wouldn't be pure enough for you, @adamralph.

[blairconrad]

My work-in-progress can be seen at http://bfakeiteasy.readthedocs.org/.

That's what will become the 2.0 version. I've exported the wiki pages, cleaned up the formatting, added titles to the top, and changed the internal links (the wiki format did not work).
I'm about to give them a read-over, just to make sure things look good and all the links are still valid and whatnot.

I'd like your opinion on some things, @adamralph and @thomaslevesque:

1. I'm inclined to remove from the 2.0.0 documentation all the notes that refer to how things changed between 1.x versions. Like the footnotes on the Bootstrapper page. We'd be making the 2.0.0 documents a clean break from the 1.x version.
2. Moving forward, we could add notes about the evolution of behaviour in 2.x, if we're so inclined. Although maybe with ReadTheDocs ability to host different versions of the documentation, there's less need.
3. Since there will be no pre-1.25.3 versions of the documentation, I would keep the footnotes in the 1.25.3 of the documents, which I'll produce after the 2.0.0 version.

All sound okay?

[thomaslevesque]

Great job @blairconrad!

I'm inclined to remove from the 2.0.0 documentation all the notes that refer to how things changed between 1.x versions. Like the footnotes on the Bootstrapper page. We'd be making the 2.0.0 documents a clean break from the 1.x version.

It would probably be useful to have a page showing all the changes in 2.0.0, to make it easier for people to migrate to 2.x. If the information is scattered on many different pages, it will be harder to find.

[blairconrad]

There is the Changes in version 2.0 page. Is that what you're suggesting, @thomaslevesque?
Although I wonder if we wouldn't (and it doesn't have to be done in in this step) be better off just putting the release notes in an .md and having it included in the docs.

[adamralph]

Agreed, stable should be the default. Each time we release a major we can also explicitly build the previous major tag, so that people can still access it.

[adamralph]

Waffle auto-magically assigned me when I raised #650.

I've raised an issue with Waffle for turning off this auto-magic - https://github.com/waffleio/waffle.io/issues/2479

[adamralph]

@blairconrad do you need any help with:

• remove content from wiki, pointing at ReadTheDocs

?

[blairconrad]

@adamralph, I'm happy for you or anyone to go ahead. It's not that it's overly difficult (I think), but I've been distracted by the other issues.
If you'd rather not do it, but are bothered by it being open, I can move it to the top of the list.

[adamralph]

@blairconrad I'll see what I can do.

It's not so much "bothered by it being open" but more "what's left to do to release 2.0".

[adamralph]

All done!

[blairconrad]

Not to complain, but I'd've thought the readme's Documentation link wouldn't point at the wiki anymore.

[adamralph]

Oops!

[blairconrad]

Are we planning on retaining the "Changes in 2.0" wiki topic forever, or just until we actually release, when people can read the release notes?
If forever, it's full of broken links!

[adamralph]

I almost removed it, but then I thought I'd leave it in until the release is published. Good point about the broken links 😁

It's a shame we can't make the draft release public. Perhaps we should copy the contents of the draft release into that wiki page for now, to fix the links?

[adamralph]

Is there any reason that the draft release is not using fenced code blocks (but the wiki page is)?

[blairconrad]

My memory is fuzzy, but the draft release was probably recreated from the readthedocs docs before they were removed, and it doesn't like the fenced code blocks in lists.

[blairconrad]

I've added fenced code blocks to the release notes and copied to the wiki.

[blairconrad]

I probably should've just put it in the wiki and made the release notes a pointer to the wiki (for now).

[adamralph]

👍 thanks v much @blairconrad

[blairconrad]

This issue has been fixed in release 2.0.0.