[sakai-pmc] Revising/trimming Sakai developer and install documentation

[Noah Botimer]

I like GitHub Pages and I like Jekyll. I do not like the idea of us writing docs as HTML by hand (grep sed what?).

There are also plenty of other static site generators out there, too, if we needed to get exotic.. The simplest thing would be to use pretty vanilla Jekyll + Pages, since it's basically wiki markup (Markdown/GFM) with 30 seconds of front matter per page. I like simple. There's plenty of room to grow with Jekyll too.

There is a roundabout way to convert a Confluence page to Markdown if there is substantially usable content:

https://answers.atlassian.com/questions/235590/answers/5702946

I'd expect that enough of the "extra stuff" would be stripped as to be a fair starting point for hand editing and whatever dressing up (code blocks/highlighting/links/macros).

Let's keep in mind that it's super easy to use GFM/MD in the app source and get nice enough rendered pages for stuff that should be kept in line with particular versions. The magical "hey, start here" site should probably be less temporal and pretty limited -- high level stuff and links back to .md's in master for detail are quite alright with me, given the stated dev audience. It's relatively easy to make three or four screens of content approachable and attractive while leaving the ugly source-y details ugly and source-y.

I really like the Tsugi example. Except for the HTML instead of GFM and the commit messages. :-)

Thanks,
-Noah

On Jan 6, 2015, at 12:54 PM, Anthony Whyte wrote:

> Perhaps an approach like the following done for Git:
> 
> http://rogerdudler.github.io/git-guide/ 
> 
> On Tue, Jan 6, 2015 at 10:01 AM, Charles Severance <csev at umich.edu> wrote:
> My $0.02 is that I would like to move the essential developer documentation into github and make a web site like a typical github application.
> 
> http://csev.github.io/tsugi/
> 
> We can still use Confluence for building / thinking - but I think that it is a good idea to just build the dev documentation in github like a normal open source project.
> 
> /Chuck
> 
> On Jan 6, 2015, at 5:47 AM, Steve Swinsburg <steve.swinsburg at gmail.com> wrote:
> 
>> Yeah that's a good idea. We could migrate this page over:
>> https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>> 
>> I'm all for using Confluence where appropriate (collaboration, meetings, sharing stuff, writeups) but it just get so out of date and irrelevant for technical doco so quickly.
>> 
>> cheers,
>> Steve
> 
> 
> _______________________________________________
> sakai-pmc mailing list
> sakai-pmc at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-pmc
> 
> 
> _______________________________________________
> sakai-pmc mailing list
> sakai-pmc at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-pmc

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-pmc/attachments/20150106/3d6a33db/attachment.html