lucenenet-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Ball <joshua.g.s.b...@gmail.com>
Subject Re: Website and basic docs work
Date Fri, 26 Dec 2014 12:43:35 GMT
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 <geobmx540@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<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