Skip to content

docs consolidation - fog.io vs github wiki #1281

Closed
geemus opened this Issue Nov 15, 2012 · 18 comments

3 participants

@geemus
fog member
geemus commented Nov 15, 2012

Some discussion has been going on about where the canonical source of info should be between fog.io and github wiki. I think there are pluses and minuses on both sides so I just wanted to open this up to discussion.

@tokengeek
fog member

Either of those approaches, splits the documentation out of the fog code release cycle which I think is the biggest thing.

As per #1280 we seem to have already decided on moving hosting of fog.io to Github. I think it will be easier to update wiki content than any page content under Github pages.

I think personally I would prefer Github since we can cross reference to issues and use wiki notation. So there's a better link between them.

The process of updating the documentation just seems a bit easier and we want to reduce as many barriers to collaborators as we can.

We still use fog.io and it's theme as the high level introduction to the project but just link to more up to date documentation in the wiki.

@geemus
fog member
geemus commented Nov 19, 2012

@tokengeek - seems reasonable. I do somewhat miss the pull request portion of this as proofreading and tips on consistency could still be helpful to keep things on track. Not sure there is any way to really help with this other than keeping a close eye on updates though...

@westonplatter

@geemus @tokengeek IMO, pull request currated content is better than wiki content. I think having a PR as a barrier is simple enough and ensures. Plus, I feel more comfortable submitting stuff for public use when I know someone else has run a sanity check on it.

So, I would vote for GH pags over GH wiki.

Thoughts?

@tokengeek
fog member

@westonplatter I'm still kind of in two minds.

Pull requests really are useful and will allow a bit collaboration before documentation changes.

Another part of me is wondering about structuring and navigating around the documentation.

We have 30+ providers, several services and need a useful way to put all of these together somehow. Now https://github.com/fog/fog/wiki/_pages doesn't solve that but it's a start!

I think since we were planning to move fog.io hosting to GH pages anyway then we may as well do that with the documentation we already have.

If later we are finding problems we can look at moving parts to a wiki

@westonplatter

@tokengeek /cc @geemus yes, keep current docs. They are a great starting point.

What about docs regarding detailed features within only a specific service? EG, jparker@a5aff02. I am hesitant to put this in a wiki format. I feel docs in the code would be best. But that's me.

Thoughts?

@geemus
fog member
geemus commented Dec 5, 2012

@westonplatter - one (at least potential) downside wrt pages instead of wiki is just that it tends to make things more complicated for editing/generating content. You probably would have to install/run things to generate the html from markdown (or some such), whereas wikis kind of "just work". Really specific stuff like what you mentioned is tricky, it might fit ok in a S3 specific page, but could also have its own page nested under the S3 page (if it was more complicated/warranted deeper explanation). This may be a more case-by-case thing, definitely worth further discussion.

@tokengeek - navigation is definitely tricky, we should perhaps make some index pages that you can start from, something where navigation might look like Fog > Compute > AWS or similar. Something worth discussing further.

Seems like, regardless, the first step is just getting fog.io on github pages. Then we can decide from there if that is "good enough" and either restructure to provide better access as-is or move to wiki if it seems untenable.

@westonplatter

@geemus I'll second "regardless, 1st step is getting fog.io on githubpags". Anyone have GH preferences?

I know a lot of people use Jekyll. Personally, I'm more familar with Octopress (jekyll variant).

Thoughts?

@geemus
fog member
geemus commented Dec 10, 2012

@westonplatter - haha, thanks for taking my rant and redirecting it toward actionable next steps! I personally have used octopress most recently and it seems good, but I don't have particularly strong feelings if other people have suggestions.

@tokengeek
fog member

I have moved the existing Jekyll pages lock, stock and barrel to the gh-pages branch so we now have busted documentation here: http://fog.github.com/fog/

It needs links fixing and the CNAME file setting up before we get to the DNS stuff but more importantly we have done something!

If we want to switch to Octopress later we can do.

@tokengeek
fog member

So for consolidation we need to:

  • fix up pages on Github
  • remove docs from master branch

One thing we might want to decide on now however, is if fog.io wanted to be an organisation set of pages which lived in it's own repo rather than a project set of pages living in a branch.

I didn't have access to create a new repo for that so just did the project approach.

@geemus
fog member
geemus commented Dec 28, 2012

@tokengeek - ah ha, this answers my questions around this from the other issue. I had thought having it as it's own repo would be better in many ways. I'll refresh my memory on gh-pages related things around this and make that change if it makes sense shortly (and start trying to fix some of the other stuff).

@geemus
fog member
geemus commented Dec 28, 2012

@tokengeek - I'm going to nuke that branch in favor of fog/fog.github.com (which I'll add you as collaborator on).

@geemus
fog member
geemus commented Dec 28, 2012

Going to close this (there is still work to do on fog.github.com but I'm on it and I don't want to forget and leave this).

@geemus geemus closed this Dec 28, 2012
@tokengeek
fog member

@geemus That's fine with me.

It'll be nicer having a project for the site rather than it hanging off some code.

Makes even more sense when going modular where fog may consist of many repositories.

@geemus
fog member
geemus commented Dec 28, 2012

@tokengeek - yep, should be cut over now (I switched the dns too, but it doesn't seem to have propogated yet). I also fixed up a couple asset related things so I think it looks more or less the same. This does (at least for the time being) remove the ability to browse to versioned docs, but analytics seem to indicate almost everyone is just looking at most recent anyway.

@tokengeek
fog member

Re versioned docs. I hope having the API docs versioned is enough for most people.

I think the approach we did have allowed versions of the site and perhaps examples but that would have meant many slightly different copies of the site floating about.

Not sure if/how that would have negatively affected search rankings/seo by duplicating content everywhere.

I think if the main site is the definitive source it makes most sense that it reflects the latest.

@tokengeek
fog member

DNS is updated for me by the way.

@geemus
fog member
geemus commented Dec 28, 2012

@tokengeek - yeah, I think API docs versioned should be good enough in almost all cases (the exception probably being right around a major release if/when we change bigger things). This should definitely consolidate and simplify things as well as help with searching I hope. Yep, dns looks to be updated for me now also (I think I mostly just needed to clear my browser cache).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.