One thing that I think is important... When it comes to adding contributors and future committers to the project, if everything is in markdown it is so easy to add people, to accept contributions, to merge them in, or even to cherry pick them. Think of any of the git based tools for cherry picking, select which changes to accept or reject. Anyone from anywhere can clone the repo, send a pull request for an update to documentation. That to me, is kind of the ultimate for an open community. Make it as easy as possible to allow people to contribute changes.
On Thu, Sep 24, 2015 at 4:53 PM, Santosh Marella <smare...@maprtech.com> wrote: > I think we should make Wiki the single place for the project documentation. > > Github and Website can both point to Wiki for documentation. > Github can have some basic steps for developers to setup and try out > Myriad. > Website can be updated often with project updates such as dev sync meeting > minutes/events/roadmap/"powered by" etc > > Santosh > > On Thu, Sep 24, 2015 at 1:18 PM, Ruth Harris <rhar...@maprtech.com> wrote: > > > I think we need a consensus. > > Here are the Pros and Cons. > > > > 1. The original markdown files are in the Myriad Github. Some are > updated; > > some are not. When the Git branch is cloned and pulled (as in downloading > > Myriad to use), the doc directory goes with it. > > 2. Updated documentation is in the Myriad Wiki. In the Wiki, it's easier > to > > do reviews. But are inconsistent with the markdown pages in Git (unless I > > do double work keeping them in sync). > > 3. Using Git pages to a website is another method of distribution. The > > markdown files could go with the code when someone downloads Myriad and > > also be used to create a website look and feel to access for information, > > discussion, etc. > > > > Anyway, I game to use markdown source and git pages to produce a website. > > > > Note: I know markdown. I'm just more concern about having a file that can > > establish an order or structure (TOC). > > > > --Ruth > > > > On Thu, Sep 24, 2015 at 12:36 PM, Jim Scott <jsc...@maprtech.com> wrote: > > > > > Ruth, et al., > > > > > > Question, are we planning on moving documentation / wiki into markdown? > > > > > > Aside from that regarding learning markdown, I just wrote my entire > > Getting > > > Started with Apache Spark book in markdown. I will be more than happy > to > > > help anyone out that needs it with what will amount to about a 15-30 > > > minutes of education on Markdown. :-) > > > > > > Jim > > > > > > On Thu, Sep 24, 2015 at 1:29 PM, Ruth Harris <rhar...@maprtech.com> > > wrote: > > > > > > > HI Jim, > > > > > > > > I like #1. It's nice and clean. > > > > Re: markdown -> html on a website. I want to do this. > > > > > > > > But for consistency sake, the Wiki content needs to be reviewed and > > then > > > I > > > > can merge, add, etc... markdown files. I don't want to maintain 2 > sets > > of > > > > docs, so after the Wiki content is review and migration to > > > > markdown/gitpages, we'll need to end-of-life the wiki info. > > > > > > > > I have a basic understanding of how to structure markdown files so > that > > > > they have some order/structure to them, but I'll probably need some > > help > > > > getting things rolling on the Doc side. > > > > > > > > --Ruth > > > > > > > > Ruth Harris > > > > Sr. Tech Writer, MapR > > > > > > > > On Thu, Sep 24, 2015 at 10:36 AM, Jim Klucar <klu...@gmail.com> > wrote: > > > > > > > > > Hi everyone, > > > > > > > > > > I started in on mocking up the site. I got tired of the bootstrap > > > navbar > > > > on > > > > > top approach so I came up with a few mock ups. Don't worry about > the > > > > colors > > > > > not being right or whatever details that are off. > > > > > > > > > > 1) http://imgur.com/Or5Fkbx > > > > > 2) http://imgur.com/2ok8T98 > > > > > 3) http://imgur.com/al0gGht > > > > > > > > > > More importantly, I plan on implementing it using Jekyll ( > > > > > https://jekyllrb.com/) This is how github pages is done. > > > > > https://pages.github.com/ > > > > > > > > > > Basically Jekyll parses markdown files and injects them into HTML > > > > templates > > > > > and generates a static site. The main advantage is it is really > > > > blog-aware > > > > > so we can create new release notices, blog entries, etc by writing > a > > > > > standalone markdown file and recompiling the site. The other > > advantage > > > is > > > > > we can redesign the website later and all the content won't have to > > be > > > > > ported. Jekyll will just inject the markdown content into the new > > site > > > > > design. > > > > > > > > > > Let me know what you think. If there aren't any objections to > Jekyll > > I > > > > can > > > > > get started and we can quibble about design later. > > > > > > > > > > Jim > > > > > > > > > > > > > > > > > > > > > -- > > > > Ruth Harris > > > > Sr. Technical Writer, MapR > > > > > > > > > > > > > > > > -- > > > *Jim Scott* > > > Director, Enterprise Strategy & Architecture > > > +1 (347) 746-9281 > > > @kingmesal <https://twitter.com/kingmesal> > > > > > > <http://www.mapr.com/> > > > [image: MapR Technologies] <http://www.mapr.com> > > > > > > Now Available - Free Hadoop On-Demand Training > > > < > > > > > > http://www.mapr.com/training?utm_source=Email&utm_medium=Signature&utm_campaign=Free%20available > > > > > > > > > > > > > > > -- > > Ruth Harris > > Sr. Technical Writer, MapR > > > -- *Jim Scott* Director, Enterprise Strategy & Architecture +1 (347) 746-9281 @kingmesal <https://twitter.com/kingmesal> <http://www.mapr.com/> [image: MapR Technologies] <http://www.mapr.com> Now Available - Free Hadoop On-Demand Training <http://www.mapr.com/training?utm_source=Email&utm_medium=Signature&utm_campaign=Free%20available>
