Re: Website and basic docs work

[Itamar Syn-Hershko <it...@code972.com>]

Wow the Aurora website does look really good. Would love to have something
like that for Lucene.NET. We already have a nice looking logo...

Prescott, can you get on writing the cotributing FAQ like we discussed in a
previous thread?

--

Itamar Syn-Hershko
http://code972.com | @synhershko <https://twitter.com/synhershko>
Freelance Developer & Consultant
Author of RavenDB in Action <http://manning.com/synhershko/>

On Fri, Dec 26, 2014 at 2:43 PM, Joshua Ball <jo...@gmail.com>
wrote:

> There wasn't really much 'design' in what I did. ;-) I just setup a simple
> BS site. My design and css skills are pretty much non-existent.
>
> However, I am happy to help anyway I can. If someone wants to organize and
> flush out the lucene.net version of docsite
> <https://github.com/apache/incubator-aurora-website>, and send me the
> github repo, I can work on some of the documentation, and send PR's of the
> MD files.
>
>
>
> On Wed, Dec 24, 2014 at 12:03 PM, Prescott Nasser <ge...@hotmail.com>
> wrote:
>
> >
> > 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: thoward37@gmail.com
> > > Date: Tue, 23 Dec 2014 14:55:24 -0800
> > > Subject: Re: Website and basic docs work
> > > To: user@lucenenet.apache.org
> > >
> > > 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 <
> joshua.g.s.ball@gmail.com>
> > > 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 <
> > > > mherndon@michaelherndon.com> 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 <
> > geobmx540@hotmail.com
> > > > >
> > > > > 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<ma...@gmail.com>
> > > > > > Sent: ‎12/‎22/‎2014 9:02 AM
> > > > > > To: user@lucenenet.apache.org<ma...@lucenenet.apache.org>
> > > > > > 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 <
> > > > itamar@code972.com>
> > > > > > 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 <
> joshua.g.s.ball@gmail.com>
> > > 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 <
> > > > mherndon@michaelherndon.com> 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 <
> > geobmx540@hotmail.com
> > > > >
> > > > > 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<ma...@gmail.com>
> > > > > > Sent: ‎12/‎22/‎2014 9:02 AM
> > > > > > To: user@lucenenet.apache.org<ma...@lucenenet.apache.org>
> > > > > > 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 <
> > > > itamar@code972.com>
> > > > > > 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/>
> > > > > > >
> > > > > >
> > > > >
> > > >
> >
> >
>