There are certainly advantages to github pages; some of which may of course be subjective:
- I actually do enjoy markdown, and prefer it over the wiki syntax. I cant recall how many times I have tried to get something in bold or italic formatting on the wiki and just gave up. Markdown gives better control and there are plenty of excellent tools that providing authoring features, with github rendering syntax support and previews, etc - There is value in keeping documentation near the code. In some sense, documentation is code :) I also prefer that the official doc is maintained and authored by the dev team and we can still open up the old wiki to others who wish to share their experience with CAS, integrating with or deploying it into xyz. - If I am not mistaken, github pages also through branching allows us to maintain versions of the documentation per release. Much much better than info snippets here and there, or separate wiki pages as we have now. This is really the biggest win from my point of view. The uPortal manual has actually done a great job organizing notes per release and I suspect if we were to similarly go that route, it would take much longer compared to starting from half scratch. The only drawback might be in taking pull requests and the trouble someone would have go through to create and submit one. This may not be that big of a deal, and I suppose we could always take offline contributions and turn them into markdown. Misagh ----- Original Message ----- From: "Marvin Addison" <marvin.addi...@gmail.com> To: cas-dev@lists.jasig.org Sent: Monday, January 6, 2014 7:47:20 AM Subject: Re: [cas-dev] CAS 4.0 Documentation > - 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: mmoay...@unicon.net 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
