George,

I found some more content for the website. There are several books written on 
Lucene, and even one on Lucene.Net. Not many open source projects can say they 
have a book written about them, so I think we should tout that fact even if the 
books do have bad reviews.

1. Instant Lucene.Net: 
https://www.amazon.com/Instant-Lucene-NET-Michael-Heydt/dp/1782165940
2. Lucene 4 Cookbook: 
https://www.amazon.com/Lucene-4-Cookbook-Edwood-Ng/dp/1782162283
3. Lucene in Action, Second Edition: Covers Apache Lucene 3.0: 
https://www.amazon.com/Lucene-Action-Second-Covers-Apache/dp/1933988177
4: Building Search Applications: Lucene, Lingpipe, and Gate: 
https://www.amazon.com/Building-Search-Applications-Lucene-Lingpipe/dp/0615204252
5: Information Retrieval: Implementing and Evaluating Search Engines (MIT 
Press): https://www.amazon.com/dp/0262528878
6: There are some others, even books written in German and Chinese

Options:

1. Contact the publishers directly and ask for permission to use the images 
(can't see why that would be an issue for them).
2. Find an advertising plugin that can be tailored to only display relevant 
books.

Are you still available to complete this? What you have done looks great. We 
just need to add the remaining content and links and update the theme of that 
CGI download page to match (see my previous email for a link to the old 
repository with the website).

There is a little more work to do to get Benchmark and Replicator integrated, 
after which I will be looking into how to get the website and documentation 
into the build process. We should follow the same folder structure as the 
current website and make the docs a subfolder. Ideally, the build script will 
generate both websites and automatically update the documentation link on the 
main website to point to the latest API version, but there should also be a way 
to keep links to the API docs of every prior release in an archive. Perhaps it 
can be another page or some kind of dropdown that becomes visible when 
tapped/clicked. Either way, we will need a way for the script to automatically 
update these links (move the current documentation link to the archive, and add 
the newest version) on each release build.


Thanks,
Shad Storhaug (NightOwl888)

P. S. I apologize in advance if this reaches you more than once. I had some 
issues with my email today and made several attempts.


-----Original Message-----
From: Shad Storhaug [mailto:s...@shadstorhaug.com] 
Sent: Tuesday, July 18, 2017 2:53 AM
To: George Kinsman
Cc: dev@lucenenet.apache.org
Subject: RE: New Website

George,

FYI - I found the source code for the old website: 
https://svn.apache.org/repos/asf/lucene.net/site

I was trying to figure out how the download page 
(http://lucenenet.apache.org/download.cgi) is setup. For example, how does it 
determine what mirror to set as default?, where does it get the mirrors to 
list?, etc. Looks like it is just a wrapper around 
http://www.apache.org/dyn/mirrors/mirrors.cgi. To get the current mirror list 
and "default" mirror we could either use the same approach with cgi or it looks 
like we could do this using JavaScript: 
https://stackoverflow.com/questions/8962757/executing-a-cgi-script-via-javascript

Hah - they also tried to do something with that green Lucene logo - but it 
really turned out bad: 
https://svn.apache.org/repos/asf/lucene.net/site/images/lucene_net_green_460.GIF


Thanks,
Shad Storhaug (NightOwl888)



-----Original Message-----
From: Shad Storhaug [mailto:s...@shadstorhaug.com] 
Sent: Tuesday, July 18, 2017 12:05 AM
To: George Kinsman
Cc: dev@lucenenet.apache.org
Subject: RE: New Website

George,

Before I get into responses, what I am thinking would work best is melding 
together the best ideas from these 4 websites we have to draw on:

1. https://simpleinjector.org/index.html
2. https://autofac.org/
3. https://lucenenet.apache.org/
4. https://lucene.apache.org/

The first 2 in terms of design and organization. The second 2 in terms of 
content.

> 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?  

I would consider the link to signing up for the mailing lists (since it 
effectively is Apache's replacement for an issue tracker on GitHub) to trump 
the mail archives, but other than that I agree this looks like a good "short 
list" for the top of the site.

I was hoping you could find the right balance to organization. But as I 
mentioned above, I like the way SimpleInjector organizes the data - in 
particular they have the "Learn", "Use", and "Engage" links at the bottom. 
Autofac also organizes their links similarly. Maybe we need to do some 
re-categorizing because our "Use" category would be full but our "Engage" 
category only has "Contribute" (well, I guess we could put a link to Apache's 
site there and maybe a link to a page with known users of Lucene.Net) and our 
"Learn" only has "Wiki" and "API" (and I guess user list mail archive), but you 
get the general idea. I am pretty sure all of those icons are available as 
fonts via Bootstrap, so doing something like this should be pretty 
straightforward.

That said, those links are just ideas I am putting out there. I don't consider 
this an exhaustive list - I am sure by going through the Lucene and Lucene.Net 
websites there might be a slightly different way to arrange them (for example, 
we should probably make a similar "download" page with all of the info about 
checking the hashes - https://lucenenet.apache.org/download.cgi - and put the 
download latest and archive links on it), and there are probably more links we 
need to uncover.

For example, should we have a Twitter account? Do we have a Twitter account for 
that matter? And maybe we could have a forum someday, but for now I think we 
can rely on the mailing lists and StackOverflow for providing support, since 
both are pretty active with people willing to help.

Oh, and I forgot to mention to link to Lucene's site, and there must be a place 
with better graphics that we can either build or link to that describes what an 
inverted index is (rather than http://lucene.sourceforge.net/talks/pisa/). 

Code Samples

I agree with you and like to have the code front and center demonstrating first 
and foremost that the library is easy to use, rather than spending a whole day 
trying to determine whether the library is easy to use by experimenting. The 
only thing I don't like is that when you are down in the API docs you have to 
link offsite from there to view them. There must be some solution where we can 
put them in both places without having to navigate off site and without having 
to duplicate content...

Calling Dispose() in practice cannot be safely done without a try-finally 
block. A using block can be done in fewer lines. Also, I recently discovered 
that you can chain multiple using statements together rather than nesting them, 
which cuts down even more on lines of code and indentation 
(https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.Demo/Facet/SimpleFacetsExample.cs#L102-L103).
 The problem with samples that don't show best practices is that most people 
will not follow the best practices if they are not in the sample. A good 
example (of a bad example) of this is the default route in MVC - almost 
everyone copies and pastes it, which produces one route that entirely overrides 
the other one rendering the second one totally unreachable. If there were only 
a simple example of how to make a proper route to override the default in the 
MVC generated template, it would save thousands of people from making the same 
mistake the first time they try it. I don't think it would be a good idea to 
assume the reader already knows how to properly call Dispose() or use a using 
block.

> I'm curious which parts you're referring to as extra?

I was referring to the organization of the Lucene.Net.Demo code into methods, 
and all of the extra code that is required to interact with the Console UI 
(other than perhaps Console.WriteLine). The quick start should just show it all 
in one lump and assume that the end user will know enough about best practices 
to organize the code into methods (which you are doing already). Ideally, the 
index sample will be self-contained (that is contain its own sample data for 
indexing in a data structure that is pre-initialized), and should be written to 
run on any platform without changes as much as possible. I don't think it would 
be a bad thing if we had to show 30-50 lines of code in order to make a sample 
that works.

I suppose technically it is possible to make both the index and search into a 
single sample that would make the job easier to run. But then people might have 
trouble trying to dissect the code to do what you would need to in the real 
world (index out of band with search). So, two samples is a must. But we don't 
need all of the extras such as NRT, non-standard analyzers, etc. Just the bare 
metal code to get the job done in the most generic way - let the user dive into 
the API docs (hopefully we can write some good tutorials there) to find the 
advanced options.

> 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.'

Technically, much of this was automatically ported using a tool, and it is 
still for the most part a line by line port of Lucene. We only diverged in 
places where differences in architecture and conventions differed between .NET 
and Java (for example Disposable(), renaming "Comparator" to "Comparer", 
differences in generics, etc).  We are also using the same binary format for 
index files as Lucene 4.8.0 so you can create an index in Java and read it in 
.NET and vice versa (some more content to add).

I am hoping to add some more extension methods and a POCO to Document mapper of 
some sort (like in Lucene.Net.Linq), but those will be in addition to the Java 
ported code, not changes to it.

> 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.

The end game is to create an API docs home home page similar to Lucene 
(https://lucene.apache.org/core/4_8_0/) that describes all of the packages (I 
haven't checked how the API docs are progressing - this might already be in 
place). I also listed them on GitHub to link to the NuGet packages. I think all 
we need on the web site is that link I supplied previously to all of the NuGet 
packages 
(https://www.nuget.org/packages?q=Author%3A%22The+Apache+Software+Foundation%22+Tag%3Alucene.net)
 - that way if/when the rest of the remaining packages are ported, we won't 
need to change the web site. NOTE: There will be 2 (maybe 3) more packages to 
add to that list plus the new CLI tool in the next beta release which I am 
working on putting together now, after which there will be 4 more remaining to 
port over.

NOTE: The API docs also have some content you can utilize or adapt to a .NET 
version to use (or when the time comes, link to).

> 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.)

I think that keeping the branding similar between Lucene.Net and Lucene is 
helpful to make it easy to identify that this IS Lucene, but running on the 
.NET platform. The font they used I think is supposed to look "dated" by 
design, just like when you go to the Apple store and you see all of those 
"modern but old" 1950's style Fender guitar logos (latest technology hiding 
behind old marketing techniques and antiquated looking designs).

But I am not in love with the puke green color. I would be happy to change it 
to a nice royal blue to match our current themes for the API docs and the web 
site (it is just a little more work to do, that is all). Frankly, I think 
anyone who drifts too far away from a standard Arial or Verdana font for a logo 
is making a mistake, but I believe keeping similar branding with Lucene (with a 
.NET twist) is a bit more important than that. If you can look at the logo and 
make the connection between both Lucene and .NET, I think we have hit our goal.

That said, the Lucene logo looks much better at 200px than 300px. Perhaps I 
should just make the whole thing smaller so it won't be so wide - I could 
probably get it down to 400-450px wide and make a smaller one that is about 2/3 
of that so it isn't so difficult to work with. I could also add a bit of extra 
border so it positions better without having to fix it up with CSS (much like 
the one you have now). Just let me know what works best for the size and I will 
build to that spec.

Also, I could convert that magnifying glass into vector graphics so they scale 
down better. Or we could use a different one. I originally chose it because it 
had a big lens area, so I could put "magnified" content in it for 
BoboBrowse.Net (https://github.com/NightOwl888/BoboBrowse.Net#readme). But if 
there is no content in it we could just as well use a smaller one.

DEMO

I just noticed that Lucene also has a demo search box on their site. I don't 
know what good a search would do on what will likely be a small site with a few 
pages, but it would be a cool feature if we had an interactive online demo of 
Lucene.Net in action, especially if we could put together a faceted search demo 
drilling down into data. Let's consider that a wish list item - a "could have", 
not a "must have".


Thanks,
Shad Storhaug (NightOwl888)


-----Original Message-----
From: George Kinsman [mailto:geo...@georgekinsman.com] 
Sent: Monday, July 17, 2017 8:22 PM
To: Shad Storhaug
Cc: dev@lucenenet.apache.org
Subject: RE: New Website

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:s...@shadstorhaug.com] 
Sent: Monday, 17 July 2017 6:35 AM
To: George Kinsman <geo...@georgekinsman.com>
Cc: dev@lucenenet.apache.org
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:geo...@georgekinsman.com] 
Sent: Sunday, July 16, 2017 8:41 PM
To: dev@lucenenet.apache.org
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 <s...@shadstorhaug.com>
Sent: 08 July 2017 17:37
To: dev@lucenenet.apache.org
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:geo...@georgekinsman.com]
Sent: Saturday, July 8, 2017 9:48 AM
To: dev@lucenenet.apache.org
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 <s...@shadstorhaug.com>
Sent: 07 July 2017 23:32
To: dev@lucenenet.apache.org
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:geo...@georgekinsman.com]
Sent: Friday, July 7, 2017 1:20 PM
To: dev@lucenenet.apache.org
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 <s...@shadstorhaug.com>
Sent: 07 July 2017 14:56
To: geo...@georgekinsman.com
Cc: dev@lucenenet.apache.org
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:geobmx...@hotmail.com]
Sent: Friday, July 7, 2017 11:26 AM
To: dev@lucenenet.apache.org
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:geo...@georgekinsman.com]
Sent: Thursday, July 6, 2017 5:04 PM
To: dev@lucenenet.apache.org
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: dev@lucenenet.apache.org


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:s...@shadstorhaug.com] Sent: Thursday, July 6, 2017 1:41 PM To: 
dev@lucenenet.apache.org 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:geobmx...@hotmail.com] 
Sent: Friday, July 7, 2017 3:35 AM To: dev@lucenenet.apache.org 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:s...@shadstorhaug.com] Sent: Thursday, 
July 6, 2017 1:13 PM To: dev@lucenenet.apache.org 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 
(list-subscr...@lucenenet.apache.org) 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)

Reply via email to