lucenenet-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Prescott Nasser <geobmx...@hotmail.com>
Subject RE: Website and basic docs work
Date Wed, 24 Dec 2014 20:03:15 GMT

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<mailto:joshua.g.s.ball@gmail.com>
> > > > Sent: ‎12/‎22/‎2014 9:02 AM
> > > > To: user@lucenenet.apache.org<mailto:user@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<mailto:joshua.g.s.ball@gmail.com>
> > > > Sent: ‎12/‎22/‎2014 9:02 AM
> > > > To: user@lucenenet.apache.org<mailto:user@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/>
> > > > >
> > > >
> > >
> >
 		 	   		  
Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message