I'm a fan of putting the documentation where Marvin is suggesting. I agree that there will be some initial hurdles in the process of upgrading, but I think overall our documentation will look more professional and hopefully be more up-to-date.
I do agree that we need a user contributed section of "recipes" or whatever everyone calls them these days. Where is the best spot for that? In Confluence? GitHub Wiki pages? Also it is worth attempting to skin the page to look similar to either the Jasig or Apereo pages? On Mon, Jan 6, 2014 at 9:47 AM, Marvin Addison <marvin.addi...@gmail.com>wrote: > > - on one hand, I'm not sure to understand why we should give up on our > "old" > > wiki if it is just a matter of organizing and updating properly the > content > > for 4.0 > > The wiki is such a mess that it was simply easier for me to start > fresh. That's mostly a reflection of my personality than anything > else, but I figured that the value of the resulting content was > worthwhile regardless of approach. > > > - on the other hand, the documentation you provide is really impressive > in > > terms of quality and quantity. > > The hard part was coming up with an organizational system and writing > content. It will be straightforward to port it to another platform if > we decide to do so. > > > I wish you had written all this great content and reorganize on our "old" > > wiki. > > I never would have started. Every time I go to CASUM I leave in > frustration. > > > BTW, do you intent to keep the "old" wiki? > > Yes, I think it has value. Many projects have a two-tiered > documentation system: a curated set of "official" documents produced > by the development team and a publicly editable wiki for community > contributions. I think that provides the best of both worlds, but it > does put a burden on the development team to produce and maintain an > official body of documentation. I think we can do it and it's worth > the effort. > > > I notice we have also a third documentation source: > > https://github.com/Jasig/cas/wiki on which I started to contribute > (maybe > > before you started the Github pages). > > Should be easy to port. We can get at the wiki source, which is > markdown, which is what I've used for GH pages. > > > Do we keep it as well? > > No, I think that GH pages would replace it. > > > I'm not as enthusiastic/optimistic as you with the editing process of the > > Github pages. > > Fair enough. Maybe I should have described it a bit. > > > Editing the wiki is easy as you don't really need to care about the > markup > > and can preview content before you save it (just by clicking on a > button). > > Not as easy to preview, but there is a reasonable process to preview > before commit. You just run the jekyll processor on the markdown > source, then hit the generated documentation root in your browser with > a file:// URL. It looks exactly like what you see on github.io. > > > I'm pretty sure that we won't have this simplicity using the Github > pages. > > Not as simple, true, but certainly still reasonable. > > > It seems to be a negative response from me, but I want to be sure we're > > heading the right direction on this. > > I would love for some other developers to offer an opinion. > > M > > -- > You are currently subscribed to cas-dev@lists.jasig.org as: > scott.battag...@gmail.com > To unsubscribe, change settings or access archives, see > http://www.ja-sig.org/wiki/display/JSG/cas-dev > -- You are currently subscribed to cas-dev@lists.jasig.org as: arch...@mail-archive.com To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev
