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/> > > > > > > > > > >
