Works for me - I will start on the documentation on the wiki - since that is probably where I can be most helpful of the three tasks. (anyone feel free to jump in with this) Troy you've got the tooling -- Joshua - do you want to take a stab at taking your design and cutting it out into something that can be used by the Aurora's tooling system? (anyone feel free to jump in) Does that sounds like a reasonable plan of attack?
> From: [email protected] > Date: Tue, 23 Dec 2014 14:55:24 -0800 > Subject: Re: Website and basic docs work > To: [email protected] > > Hi! > > Great to see that folks want to contribute to this, and sorry for the delay > in getting this started. Thanks for the nudge, Itamar. There's a good > reason for that though.. :) > > One of my coworkers on the Twitter OSS team (Dave Lester) helps to maintain > ASF Aurora and Mesos project docs. He recently built an easy-to-use system > for managing the front-page and docs sites for Aurora. We worked together a > bit on getting the tool working and I realized this would be great for > Lucene.Net as well. Right now, it's purpose-built just for the Aurora > project, but it would be pretty easy to generalize for any ASF project. We > were planning to do that work and make a generalized tool over the first > week of January. I was thinking we could apply that to Lucene.Net as our > first test project. > > Here's the current code for the Aurora site generator: > https://github.com/apache/incubator-aurora-website > > Not sure if sticking with Ruby is the best way to go, since it's not always > available or easy to install (especially on Windows systems). Node.js might > be a better choice and wouldn't be hard to re-implement that using common > Node.js tools instead of Ruby. > > But that's not the only thing to think about. There are a lot of different > aspects to this project: > > - Design for site/docs pages > - Update site/docs content > - Tooling to build and maintain site and docs (ideally in a CI process > triggered from post-commit hook) > > Joshua - I appreciate what you've done on the site, and the design already > looks much better than the current site. That said, I think it's a bit > over-engineered with all the JS. It's a website, not an app, so doesn't > really need Durandal/Knockout. We could probably do just fine with a static > site and it would make it easier for folks to work on. We shouldn't expect > folks have to learn/understand JS and Knockout just to update the site. > > I'd like to see the content live in Markdown, which is pretty > technology-agnostic and universally understood at this point. It's also > easy to read if you're looking through the repo in text-mode. > > I like Michael's idea of keeping a simple Bootstrap-style homepage, with > most of the content on that page, then have a separate section for docs > that has a table-of-contents in a sidebar. I've used that model a bunch in > other projects and it works really well. > > Prescott suggests using the wiki for docs, but personally, I'm not a big > fan of that method. Wikis tend to make it hard to find things, don't let > you do much with presentation, and get stale quickly. Having the docs live > with the code as Markdown files should make it easier to keep up with. It > also means that someone who is browsing the repo or who has cloned it, will > get the docs with the code, instead of having to find and navigate a > separate website. Also, Confluence is just a bit slow and tedious to work > with. In-browser editing sucks. I'd rather use my text editor on Markdown > files. Yada yada. I can rant about this topic for days... > > But that doesn't mean "don't use the wiki at all". IMO the wiki and docs > are separate things. The wiki is useful for coordinated work that is short > lived (like arranging board reports, and that sort of thing), but things > that are more user-focused should be in Markdown docs, rendered to a > themed-static site for easier consumption. I kind of see this divide > similar to the user/dev mailing lists. Maybe the wiki can be used for "dev" > content while the docs site is for the "user" content. The wiki is a great > place to hack out some content and get it ready. I see a natural flow of > docs living in the wiki initially, then migrating them to Markdown for the > docs site once they are stable. > > My idea for how to proceed is this... We should focus on the three areas > separately for now: > > - Design: Build a nice looking single-page static HTML/CSS design using > Bootstrap for a front-page + docs sort of site. > - Content: Create a bunch of good docs content in the wiki. We can refine > it there, then export to Markdown for the docs site once the tooling and > design are done. Until then, it's accessible in the wiki. > - Tooling: Build a simple to use, minimal setup, CLI tool for generating > the site from Markdown->HTML and deploying via git/ASF svn. Eventually make > this an automated CI job. > > I am happy to drive the tooling part of it based around a reusable tool > that can work for any ASF project. I could do the design part of it as well > (or gladly work with contributions from folks, eg Joshua, or whoever else > would like to toss some ideas around). > > Who wants to start cranking out some decent doc content in the wiki? > > Thanks, > Troy > > > On Tue, Dec 23, 2014 at 1:32 PM, Joshua Ball <[email protected]> > wrote: > > > > OK, > > here is a first stab at porting the existing site to durandal/bootstrap: > > > > https://github.com/joshball/lucene-net-website > > > > This is pretty, but I don't want to waste more time on it if this is not > > what you had in mind. > > > > If we want to go down this path, I started a branch with the contributing > > page: > > https://github.com/joshball/lucene-net-website/tree/feature/contributing > > > > Again, not sure exactly what we want here, or what many of the notes from > > Prescott are about exactly). I haven't contributed to lucene.net yet, so I > > would be a good user for this. > > > > I based the page off of http://hapijs.com/. They do a great job of making > > it easy to contribute. > > > > As for the site itself, it uses mimosa for build, > > durandal/knockout/bootstrap for the SPA. > > > > You do need node installed. And then after that, mimosa (see the readme). > > It was built on windows, so no issues there. The reason for node is to do > > all the building/min/lint/etc... > > > > Let me know your thoughts. > > > > > > > > > > > > On Mon, Dec 22, 2014 at 12:03 PM, michael herndon < > > [email protected]> wrote: > > > > > You could just create a page with bootstrap (or something similar) and > > have > > > an aside nav. The nav could then scroll down / up down the single page. > > > Also it would give you additional styles to help point out tips or calls > > to > > > action on the page. > > > > > > example of the aside nav. > > > http://getbootstrap.com/css/ > > > > > > On Mon, Dec 22, 2014 at 12:59 PM, Prescott Nasser <[email protected] > > > > > > wrote: > > > > > > > I think we have two goals - one simplify the website down to a single > > > page > > > > (we really don't have THAT much content). > > > > > > > > Two - fill out the wiki with all kinds of docs - here are my notes on > > > that > > > > (if anyone wants to run with them). Ill create stub pages if no one > > else > > > > does > > > > > > > > PMC > > > > Roles, Rules, Processes > > > > New Committers (vote and process after to complete) > > > > New PMC Member (vote, and process after to complete) > > > > Board Reports > > > > Committers > > > > How to update the website > > > > How to handle git apache mirror at github ( > > > > https://mahout.apache.org/developers/github.html) > > > > Contributors > > > > How to submit a pull request / get involved (CLA, ICLA) > > > > General > > > > How to join mailing lists > > > > Current state of the Lucene.Net world > > > > Guides > > > > Explaining the structure of Lucene.Net - analyzers, parsers, etc. > > > > Simple How to > > > > Complete how to > > > > Explain > > > > > > > > Sent from my Windows Phone > > > > ________________________________ > > > > From: Joshua Ball<mailto:[email protected]> > > > > Sent: 12/22/2014 9:02 AM > > > > To: [email protected]<mailto:[email protected]> > > > > Subject: Re: Website and basic docs work > > > > > > > > I would be happy to work on this as well. > > > > > > > > On Mon, Dec 22, 2014 at 5:43 AM, Itamar Syn-Hershko < > > [email protected]> > > > > wrote: > > > > > > > > > Hi all, > > > > > > > > > > We want to do some work on the website, to provide guidance on > > > > > contributing, guidance and some basic documentation on our process > > and > > > on > > > > > getting started with using the code. > > > > > > > > > > Is there anyone interested in joining the effort? Also, I recall Troy > > > > > saying something about wanting to leading this. > > > > > > > > > > Thanks, > > > > > > > > > > -- > > > > > > > > > > Itamar Syn-Hershko > > > > > http://code972.com | @synhershko <https://twitter.com/synhershko> > > > > > Freelance Developer & Consultant > > > > > Author of RavenDB in Action <http://manning.com/synhershko/> > > > > > > > > > > > > > > > > On Tue, Dec 23, 2014 at 1:32 PM, Joshua Ball <[email protected]> > wrote: > > > > OK, > > here is a first stab at porting the existing site to durandal/bootstrap: > > > > https://github.com/joshball/lucene-net-website > > > > This is pretty, but I don't want to waste more time on it if this is not > > what you had in mind. > > > > If we want to go down this path, I started a branch with the contributing > > page: > > https://github.com/joshball/lucene-net-website/tree/feature/contributing > > > > Again, not sure exactly what we want here, or what many of the notes from > > Prescott are about exactly). I haven't contributed to lucene.net yet, so I > > would be a good user for this. > > > > I based the page off of http://hapijs.com/. They do a great job of making > > it easy to contribute. > > > > As for the site itself, it uses mimosa for build, > > durandal/knockout/bootstrap for the SPA. > > > > You do need node installed. And then after that, mimosa (see the readme). > > It was built on windows, so no issues there. The reason for node is to do > > all the building/min/lint/etc... > > > > Let me know your thoughts. > > > > > > > > > > > > On Mon, Dec 22, 2014 at 12:03 PM, michael herndon < > > [email protected]> wrote: > > > > > You could just create a page with bootstrap (or something similar) and > > have > > > an aside nav. The nav could then scroll down / up down the single page. > > > Also it would give you additional styles to help point out tips or calls > > to > > > action on the page. > > > > > > example of the aside nav. > > > http://getbootstrap.com/css/ > > > > > > On Mon, Dec 22, 2014 at 12:59 PM, Prescott Nasser <[email protected] > > > > > > wrote: > > > > > > > I think we have two goals - one simplify the website down to a single > > > page > > > > (we really don't have THAT much content). > > > > > > > > Two - fill out the wiki with all kinds of docs - here are my notes on > > > that > > > > (if anyone wants to run with them). Ill create stub pages if no one > > else > > > > does > > > > > > > > PMC > > > > Roles, Rules, Processes > > > > New Committers (vote and process after to complete) > > > > New PMC Member (vote, and process after to complete) > > > > Board Reports > > > > Committers > > > > How to update the website > > > > How to handle git apache mirror at github ( > > > > https://mahout.apache.org/developers/github.html) > > > > Contributors > > > > How to submit a pull request / get involved (CLA, ICLA) > > > > General > > > > How to join mailing lists > > > > Current state of the Lucene.Net world > > > > Guides > > > > Explaining the structure of Lucene.Net - analyzers, parsers, etc. > > > > Simple How to > > > > Complete how to > > > > Explain > > > > > > > > Sent from my Windows Phone > > > > ________________________________ > > > > From: Joshua Ball<mailto:[email protected]> > > > > Sent: 12/22/2014 9:02 AM > > > > To: [email protected]<mailto:[email protected]> > > > > Subject: Re: Website and basic docs work > > > > > > > > I would be happy to work on this as well. > > > > > > > > On Mon, Dec 22, 2014 at 5:43 AM, Itamar Syn-Hershko < > > [email protected]> > > > > wrote: > > > > > > > > > Hi all, > > > > > > > > > > We want to do some work on the website, to provide guidance on > > > > > contributing, guidance and some basic documentation on our process > > and > > > on > > > > > getting started with using the code. > > > > > > > > > > Is there anyone interested in joining the effort? Also, I recall Troy > > > > > saying something about wanting to leading this. > > > > > > > > > > Thanks, > > > > > > > > > > -- > > > > > > > > > > Itamar Syn-Hershko > > > > > http://code972.com | @synhershko <https://twitter.com/synhershko> > > > > > Freelance Developer & Consultant > > > > > Author of RavenDB in Action <http://manning.com/synhershko/> > > > > > > > > > > > > > >
