Thanks for the comments, they're hugely valuable. I've actioned most of them,
with some additional thoughts/questions on a few.
1. Fixed
2/4/5. It's a tricky balance to make I think, that's for sure! Perhaps to make
the samples more useful we could link classes in the code samples to their
respective API docs, or the additional getting started docs? I think having an
example of how the library works on the front page could be important to
introduce new users, and to act as a kind of lightweight reference for
returning users. Personally I've found other sites that do this more useful
than those that require a few clicks/page scanning to reach the 'guts' of a
library - I tend to try to intellisense from there when playing around. Perhaps
it is a bit too much code though.
The IDisposable usage is a tricky one - on the one hand the samples should most
definitely display correct usage, although such usage would break the flow and
indentation of the display as it's currently divided (with the re-use of the
writer too). Perhaps it's enough to just call dispose on the
writer/dir/analyser at the end with a comment? The sample itself could link to
some docs on how to manage the lifetimes of these objects with IoC in mind:
<a href="link-to-lifetime-docs">
// Cleanup
writer.Dispose();
dir.Dispose();
analyser.Dispose();
</a>
I actually did use that demo code to help fashion those code samples, though
apart from the obvious IDisposable/spelling error, I'm curious which parts
you're referring to as extra? The code is runnable with LinqPad after
installing Lucene.Net.Analyzers.Common (hence why I used that as the nuget
target, it seemed to be the most necessary package) but I wasn't really able to
slim it down any further while retaining some runnable code that produced
something. I toyed with the idea of linking to a downloadable LinqPad sample (I
used it to write this sample, as evidenced by the `.Dump()` calls) but wanted
to get feedback first. I'm not hugely attached to any particular strategy
here, just that I think having some code is important.
3. Those links are great - do you think they should all be as visible as the
github/mail list at the top? Maybe that area should be reserved for the most
directly useful links? At a glance the might be:
- Github
- Mailing list archives
- StackOverflow
- Nuget
- JIRA
The others could possibly go in sub-menu's at the top - That way they'd be
visible (as they're still v important) but not have so much 'air-time' so to
speak. Thoughts?
6. Totally agree - we stick to American English here too just to match
conventions with the BCL/style guides. I had it right in the code, but missed
the title!
7. Good thoughts - fixed.
8. Added to an About section lower down. I wonder if the first goal might need
a slight update, now that the project isn't so much an automated port but a
curated one. Super quick idea: ' Maintain a curated port of the Java Lucene
project in C# that follows the same direction and feature set of the Java
Lucene project.'
9. As mentioned before I used that one as Lucene.Net seemed to not be very
useful on its own, but I agree with your thinking - it's the main package. it
might be worth linking to a page somewhere (or having it further down a bit on
the main site) that explains each package. I can see there's explanations on
the github page, but perhaps with more detail.
10. Definitely some great content there! Will look to add some soon, perhaps
before the new 'About' section but after the code samples. Or maybe before.
11. Hah. Fixed :-).
In terms of logo, are you particularly attached to the Java lucene font/logo?
I've been browsing through the noun project and have found a few simple logo's
that have the search icon that could replace the current wavy thing. I'm not
sure I'm a huge fan of the classic lucene green or the font - it looks a tad
aged (though that's probably just me.)
Noun Project ideas:
https://thenounproject.com/term/search/932675/
https://thenounproject.com/term/search/24561/
Anyway, just my 2 cents - hope some of this is helpful :-).
George
-----Original Message-----
From: Shad Storhaug [mailto:[email protected]]
Sent: Monday, 17 July 2017 6:35 AM
To: George Kinsman <[email protected]>
Cc: [email protected]
Subject: RE: New Website
George,
It's a start!
Since you mentioned it, I took a crack at making some logo images by merging
together the Microsoft .NET logo (look) with the Lucene logo. I am not sure
what Apache's policy is on one project using another project's logo, so if I
went horribly wrong here somebody please tell me.
I made one wide logo (490px) for the bigger viewports and a narrow one (200px)
for the smaller viewport. Not sure if these dimensions will work, but if not
let me know what might work and I will see what I can do. The bigger one has a
magnifying glass (the international symbol for search) which feels like it
definitely needs to be there. We can then use a bigger version of the
magnifying glass on NuGet so it all matches.
I also used Lucene's colors which don't match the current theme of the website
- let me know if you prefer to change the logo colors rather than the theme.
I uploaded the images (and their .psd files) to
https://issues.apache.org/jira/projects/LUCENENET/issues/LUCENENET-589
A few comments:
1. The "unvisited" colors of the links are blue on blue which makes them blend
into the background (making them almost invisible).
2. I am a bit torn on putting the quick start on the home page vs taking Simple
Injector's approach and just linking to it on the API docs. I like the code
front and center on the site, but it seems like the quick start should be part
of the API docs so it is easy to find when you are looking at them.
3. Some other links we should have:
a. StackOverflow - https://stackoverflow.com/questions/tagged/lucene.net
b. Wiki -
https://cwiki.apache.org/confluence/display/LUCENENET/Lucene.Net (Out of date
now, but I can work on updating it now that I have access)
c. JIRA Issue Tracker -
https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open
d. Other Lucene Ports -
https://wiki.apache.org/lucene-java/LuceneImplementations
e. NuGet -
https://www.nuget.org/packages?q=Author%3A%22The+Apache+Software+Foundation%22+Tag%3Alucene.net
f. Apache website - http://www.apache.org/
g. Mailing lists -
https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists
h. License - http://www.apache.org/licenses/LICENSE-2.0
i. Latest Release -
https://dist.apache.org/repos/dist/release/lucenenet/
j. Release Archive - https://archive.apache.org/dist/lucenenet/
k. Contribution Guide -
https://github.com/apache/lucenenet/blob/master/CONTRIBUTING.md
4. If we do have the quick start on the home page, the first 2 examples should
be the simplest way to create an index and the simplest way to search it (with
none of the "extras"). Take a look at the
https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.Demo/IndexFiles.cs
and
https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.Demo/SearchFiles.cs
demos - we should have something like this, but without the console app, extra
methods, etc. - just the basic "write index" and "search index". Having
additional examples is fine, but these two should be the most prominent.
5. The code samples should always show the correct usage of putting IDisposable
types in a using block.
6. I think we should standardize on American English. Having a StandardAnalyzer
class being described as an "analyser" just looks strange to me. Or, if you
prefer to localize the site that would work too, but might be a lot more work
than you bargained for.
7. The headline should probably be "Lucene.Net is a high performance full-text
search engine library for .NET". Technically, we support .NET Framework 4.5.1+,
.NET Core, Mono, Xamarin.iOS, Xamarin.Mac, and Xamarin.Andriod, but that is a
bit wordy (https://docs.microsoft.com/en-us/dotnet/standard/net-standard). You
can use that fact as content somewhere else, though (or just say that we
support .NET Framework and .NET Standard 1.5, which would cover any future
platforms MS decides to add to .NET Standard). "Embeddable" also doesn't seem
like the right term to use:
http://internetofthingsagenda.techtarget.com/definition/embedded-software. I
know what you are trying to say, but I think the term "library" covers it,
since it sets it apart from being a "service".
8. I think it is still important to state our three primary goals on the home
page (https://lucenenet.apache.org/). Maybe they don't belong at the top,
though.
9. If we are going to have a single NuGet package manager console command, it
should be for the Lucene.Net package.
10. If you are looking for content to fill the homepage with, there is some
great stuff here: https://lucene.apache.org/core/ (although there needs to be
some fact checking against lucene 4.8.0 on each of these points) 11. It's no
longer 2016 :) (well, maybe it is in Australia).
Thanks,
Shad Storhaug (NightOwl888)
-----Original Message-----
From: George Kinsman [mailto:[email protected]]
Sent: Sunday, July 16, 2017 8:41 PM
To: [email protected]
Subject: Re: New Website
Hi there,
I spent some time over the last week on a draft version of a new website. I've
uploaded a repository to github
(https://github.com/gkinsman/LuceneNetDraftSite) with the site and build
scripts. You can run `build.ps1` to do a one time build, and `build.ps1 -watch`
to start an http server and watch script.
A sample screenshot of it is here: http://i.imgur.com/YR7wSpj.jpg. Obviously
I've made some assumptions in the sample code, and it's a very rough draft -
but it's a start, and should be quite easy to add to. I haven't touched the
logo - I don't have the skills to better the current design.
Let me know your thoughts.
George
________________________________
From: Shad Storhaug <[email protected]>
Sent: 08 July 2017 17:37
To: [email protected]
Subject: RE: New Website
A concern is the amount of maintenance involved with so many tools. We already
have a lot of them, so it would probably be best to reuse the tools we have if
possible to keep the learning curve and maintenance of the infrastructure down.
> . I'm not sure how strict the rules are on exactly *what* code needs to be
> hosted at Apache, but perhaps it might be wise to create a github org for
> Lucene.Net for non-core repositories. We could then store the static site
> there, and deploy it to apache.org as per the rules.
The lucenenet project is already part of the Apache GitHub org. I don't think
it is possible to be part of more than one organization.
I have worked with GitHub pages before and they recommended to set it up as a
different branch in the same repo. I thought it was a PITA at the time because
I had to do a git clean every time I switched between branches, but now that I
think about the workflow a bit more there could just be separate working
directories for the lucenenet project and the web site each pointing to a
different branch. So, reusing the current repo (on a separate branch) is a
possibility. We could also receive PRs for the doc updates, provided we provide
the instructions where to find them in the repo. And using a different branch
means we can easily have 2 different CI triggers so they can be independent.
> If we used something like Wyam, content updates would become a matter of
> changing/adding a new markdown document to the site repository, which could
> then be built and deployed using AppVeyor<https://www.appveyor.com/> to
> apache.org.
AppVeyor - Continuous Integration and Deployment service
...<https://www.appveyor.com/> www.appveyor.com
#1 Continuous Delivery service for Windows Your new build server in a cloud.
Start in minutes. Enjoy faster results.
No issue with using Wyam. However, we already are using TeamCity for CI and
should probably just create a separate build for the web site on TeamCity
(https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds),
so we don't have yet another tool to learn/provide permissions for. We are
also using Powershell for the build script, so it would be best to use
Powershell in this case as well as a wrapper around whatever tooling needs to
run (if necessary).
> Let me know your thoughts on what I've outlined above - I'm going to begin
> working on some ideas for design, which I'll update you with as I go. I'd be
> happy to set all of the above up, I think it comes down to where you'd be
> willing to host the static site repository, and whether you want to go down
> the GitHub org path - assuming you're happy with the direction.
It sounds like you have the right idea. Actually, I like Autofac's design even
more than SimpleInjector.
Although, it would be nice if some of the rest of the team let us know their
thoughts as well. Prescott, Stefan, Itamar, Wyatt?
Does anyone know who has or how to get access to update the existing web site,
or if it is possible to change the DNS record for lucenenet.apache.org to a new
location? The API docs are hosted on the same subdomain so this applies to that
project as well.
Recent News/Updates
Frankly, this is another thing that we really should cut out of the design
unless someone is willing to commit to keeping it updated. If we have a design
that doesn't have any dates or versions on it, it will always be current and we
don't run the risk of it looking dead even if nobody touches it for a couple of
years. I don't see any dates or version numbers on Autofac or SimpleInjector's
websites. Do we really need to announce to the world that the project teeters
on the edge of extinction because not enough people contribute? It doesn't
sound like the right formula to building a successful community.
Vote
It looks like the last release had a couple of design proposals and the team
voted on the one they preferred
(http://apache.markmail.org/message/aafm74wp556dlohm?q=lucenenet+website).
Sounds like a great way to have community involvement...but if there is only
time for one design proposal I will vote on it :).
-----Original Message-----
From: George Kinsman [mailto:[email protected]]
Sent: Saturday, July 8, 2017 9:48 AM
To: [email protected]
Subject: Re: Mailing List Documentation
SimpleInjector's site looks really good, although as you say it's important to
have some code samples on the homepage too. Some examples of project homepages
that I think do a really good job at this include
Serilog<https://serilog.net/>, Autofac<https://autofac.org/> and
Nancy<http://nancyfx.org/>. Each of them have clean designs, code samples, and
installation directions - and each of them are great examples of very active
.NET open source projects too. I think we could implement a nice modern design
with these things front and centre, which would give the project a great web
presence.
Where
Each of those projects are hosted using Github
Pages<https://pages.github.com/>, which is a static content host. They use
static generator tools like Jekyll to convert markdown from a git repository
into a plain html website. If we used something a little more modern like
Wyam<https://wyam.io/> with a custom theme, then we could just host it in a
github repo. Another thing about those previously mentioned projects is that
they each<https://github.com/autofac> have<https://github.com/serilog/serilog>
their own<https://github.com/NancyFx> GitHub org, with many separate
repositories for tooling/examples/public site etc. I'm not sure how strict the
rules are on exactly *what* code needs to be hosted at Apache, but perhaps it
might be wise to create a github org for Lucene.Net for non-core repositories.
We could then store the static site there, and deploy it to apache.org as per
the rules.
How
If we used something like Wyam, content updates would become a matter of
changing/adding a new markdown document to the site repository, which could
then be built and deployed using AppVeyor<https://www.appveyor.com/> to
apache.org. That would give us a very low barrier to entry for contributions (a
GitHub PR), and allow you guys to interact with the community really easily.
The process from an approved PR to the site being updated would be entirely
automatic. The DocFX work could be hosted in a separate repo too, which could
be hosted/deployed alongside the main site.
I completely sympathise with you that the project needs to appear to be a bit
more active - I think this would be a great step to take to let the wider .NET
community know about the enormous amount of effort you're putting into this new
port, and to pull in new contributors. I'd love to help get there however I can.
Let me know your thoughts on what I've outlined above - I'm going to begin
working on some ideas for design, which I'll update you with as I go. I'd be
happy to set all of the above up, I think it comes down to where you'd be
willing to host the static site repository, and whether you want to go down the
GitHub org path - assuming you're happy with the direction.
Cheers,
George
________________________________
From: Shad Storhaug <[email protected]>
Sent: 07 July 2017 23:32
To: [email protected]
Subject: RE: Mailing List Documentation
George,
I started a new issue on JIRA to track the progress of this:
https://issues.apache.org/jira/browse/LUCENENET-589.
The only thing that is clear about the project at this point is that we don't
really have a clear idea what is required, so the first step is to start
picking brains about what we are actually building. I would say we could
probably have that conversation here on the dev mailing list and use the
information gathered here to list and prioritize requirements on JIRA, and then
work exclusively on JIRA from there. Some of those things to nail down are
where to build it (in the lucenenet repo or somewhere else) where to host it,
and how to deploy it.
One concern is the ability to easily update it with recent news. I don't know
offhand whether it makes more sense to integrate/build some kind of simple CMS
or if that means we need to build a TeamCity task to deploy it frequently with
updates, or some other method.
Personally, my primary concern is to keep the project going. It is not
acceptable to have a web site that looks like it belongs to a project that
nobody is maintaining (when in fact we are). We should aim to make it look like
a community that people are not afraid to jump in and help with. I am partial
to SimpleInjector's design: https://simpleinjector.org/index.html with a modern
look and feel, responsive design, and links to all of the appropriate places to
get support for the product and how to get involved. A quick start guide for
Lucene.Net is also essential to learning the basics before diving into the API
docs.
Simple Injector<https://simpleinjector.org/index.html>
simpleinjector.org
Simple injector is free. Simple Injector is open source and published under the
permissive MIT license. Simple injector is, and always will be, free.
Thanks,
Shad Storhaug (NightOwl888)
-----Original Message-----
From: George Kinsman [mailto:[email protected]]
Sent: Friday, July 7, 2017 1:20 PM
To: [email protected]
Subject: Re: Mailing List Documentation
Thanks Shad, great list there. I'd be happy to work on a new public
site/design/icon this weekend - would this be the appropriate forum to post
ideas/progress, or perhaps a github issue/new repo? The DocFX docs look great
too, it'd be great to host them alongside/inside a new site.
Also as an aside (perhaps not the right thread for this), but I'm interested in
porting the TermFrequencyAttribute (patch here
https://issues.apache.org/jira/browse/LUCENE-7854) from Lucene 7 in order to
customise the method of obtaining the term frequency at index time. It looks
like the building blocks for this already exist in Lucene.Net 4.8, so I might
try and spend a little time spiking out the idea if there are no objections.
________________________________
From: Shad Storhaug <[email protected]>
Sent: 07 July 2017 14:56
To: [email protected]
Cc: [email protected]
Subject: RE: Mailing List Documentation
> I'd be willing to help out with this in whatever form. Since this project is
> an Apache one, does that preclude it from using something other than apache
> hosted docs? Something a little more user friendly like ReadMe (ReadMe.io) or
> ReadTheDocs might be useful? (ReadTheDocs.io). Both have free open source
> licenses/allowances - a great example of readme is here:
> https://docs.getseq.net/docs.
George, there is a (not so exhaustive) list of ideas of things to work on here
(https://github.com/apache/lucenenet/blob/master/CONTRIBUTING.md#other-ways-to-help).
Also see the 2 sections above for additional things that can be done to help.
-----Original Message-----
From: Prescott Nasser [mailto:[email protected]]
Sent: Friday, July 7, 2017 11:26 AM
To: [email protected]
Subject: RE: Mailing List Documentation
That's a good question - it's been a while. Stefan do you recall the rules
around this?
I also am unfamiliar with those services, but would they support the effort
underway for DocFX? I think DocFX outputs some nice HTML which should be pretty
easy for us to host at apache
-----Original Message-----
From: George Kinsman [mailto:[email protected]]
Sent: Thursday, July 6, 2017 5:04 PM
To: [email protected]
Subject: RE: Mailing List Documentation
I'd be willing to help out with this in whatever form. Since this project is an
Apache one, does that preclude it from using something other than apache hosted
docs? Something a little more user friendly like ReadMe (ReadMe.io) or
ReadTheDocs might be useful? (ReadTheDocs.io). Both have free open source
licenses/allowances - a great example of readme is here:
https://docs.getseq.net/docs.
Cheers,
George
From: Prescott Nasser
Sent: Friday, July 7, 06:45
Subject: RE: Mailing List Documentation
To: [email protected]
Since that was a while ago, I don't think it made it anywhere. Also not sure
there is a benefit to digging through the mailing list again - let's just make
this a re-ask for help? Or open up a new thread with a better subject to catch
some attention? -----Original Message----- From: Shad Storhaug
[mailto:[email protected]] Sent: Thursday, July 6, 2017 1:41 PM To:
[email protected] Subject: RE: Mailing List Documentation I have to dig
through the email, but as I recall we had 2 volunteers offer their help to
build our web site. At the time I assumed that they were being contacted
offline or on a list that I didn't have access to. Do you know if they were
replied to? Perhaps they still have the time and willingness to help...?
-----Original Message----- From: Prescott Nasser [mailto:[email protected]]
Sent: Friday, July 7, 2017 3:35 AM To: [email protected] Subject: RE:
Mailing List Documentation I couldn't for the life of me remember (or find out)
how to get you permissions. So I filed a ticket with INFRA
(https://issues.apache.org/jira/servicedesk/agent/INFRA/issue/INFRA-14530).
Definitely need to update all of our documentation and website. I'm not a web
designer - but I can help any community member who is and who wants to help us
revamp our web presence? I'm following the progress on this PR
https://github.com/apache/lucenenet/pull/206, which I think will solve our
documentation issues. Just need to get a lot of people writing up samples on
how to get started using Lucene and different features -----Original
Message----- From: Shad Storhaug [mailto:[email protected]] Sent: Thursday,
July 6, 2017 1:13 PM To: [email protected] Subject: Mailing List
Documentation Hello, We received a complaint
(https://github.com/synhershko/LuceneNetDemo/issues/3#issuecomment-307391518)
from someone who wanted to contribute, but couldn't figure out how to sign up
for the dev list because (apparently) the WIKI documentation isn't clear enough
(https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists). He tried
to signup using the *actual* email listed on the page
([email protected]) and it bounced. He also made mention of
our out of date documentation on the web site and WIKI pages. What happened
with the web site revamp project and can we get that going now that we are
officially on NuGet? People get the impression the project is dead. Also, could
someone give me access to the WIKI so I can start working on updating the docs
there? Is that the recommended place to add documentation (such as
walkthroughs, .NET platform specific setup instructions, etc.) or should we aim
to make that part of the API documentation
(https://github.com/apache/lucenenet/pull/206)? While we are on that subject,
is the plan to put the new API docs at
http://incubator.apache.org/lucene.net/docs/3.0.3/Index.html (with the new
version number), or somewhere else? Thanks, Shad Storhaug (NightOwl888)
