lucenenet-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From <nato...@gmail.com>
Subject Re: Website and basic docs work
Date Thu, 25 Dec 2014 19:42:00 GMT
I'd be willing to do the site design.






Sent from Windows Mail





From: Troy Howard
Sent: ‎Tuesday‎, ‎December‎ ‎23‎, ‎2014 ‎5‎:‎55‎ ‎PM
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