You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucenenet.apache.org by Shad Storhaug <sh...@shadstorhaug.com> on 2017/07/06 20:13:07 UTC
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-subscribe@lucenenet.apache.org<ma...@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)
Re: Mailing List Documentation
Posted by George Kinsman <ge...@georgekinsman.com>.
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 <sh...@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:george@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 <sh...@shadstorhaug.com>
Sent: 07 July 2017 14:56
To: george@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:geobmx540@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:george@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:shad@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:geobmx540@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:shad@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-subscribe@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)
RE: Mailing List Documentation
Posted by Shad Storhaug <sh...@shadstorhaug.com>.
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.
Thanks,
Shad Storhaug (NightOwl888)
-----Original Message-----
From: George Kinsman [mailto:george@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 <sh...@shadstorhaug.com>
Sent: 07 July 2017 14:56
To: george@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:geobmx540@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:george@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:shad@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:geobmx540@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:shad@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-subscribe@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)
Re: Mailing List Documentation
Posted by George Kinsman <ge...@georgekinsman.com>.
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 <sh...@shadstorhaug.com>
Sent: 07 July 2017 14:56
To: george@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:geobmx540@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:george@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:shad@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:geobmx540@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:shad@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-subscribe@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)
RE: Mailing List Documentation
Posted by Shad Storhaug <sh...@shadstorhaug.com>.
> 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:geobmx540@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:george@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:shad@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:geobmx540@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:shad@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-subscribe@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)
Re: Mailing List Documentation
Posted by Shannon Deminick <sh...@umbraco.dk>.
Hi All,
The docfx implementation I've been working on for the API Docs and now for
basically whatever docs we want to host works well, it's flexible and it
outputs static HTML. It's just a powershell build and it spits out the site
to be hosted wherever. Here's the PR (work in progress if you wish to check
it out) https://github.com/apache/lucenenet/pull/206
On Fri, Jul 7, 2017 at 4:55 PM Stefan Bodewig <bo...@apache.org> wrote:
> Hi
>
> I don't think there are any hard rules here. Source code has to be at
> Apache and the main site at apache.org, but if we want to use some kind
> of doc service that better fits our needs than a static website, that
> should be fine.
>
> That's just my gut feeling with no claim of authority, though.
>
> If we can generate static HTML that works well enough, then I don't
> really see a reason to not put it onto our own site.
>
> Stefan
>
> On 2017-07-07, Prescott Nasser wrote:
>
> > 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:george@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
>
--
*Shannon Deminick*CTO
[image: Umbraco] <http://umbraco.com>
*Umbraco A/S *
Haubergvej 1
DK-5000 Odense C
Denmark
http://umbraco.com <http://umbraco.com>
Phone +45 70 26 11 62 <+4570261162>
Re: Mailing List Documentation
Posted by Stefan Bodewig <bo...@apache.org>.
Hi
I don't think there are any hard rules here. Source code has to be at
Apache and the main site at apache.org, but if we want to use some kind
of doc service that better fits our needs than a static website, that
should be fine.
That's just my gut feeling with no claim of authority, though.
If we can generate static HTML that works well enough, then I don't
really see a reason to not put it onto our own site.
Stefan
On 2017-07-07, Prescott Nasser wrote:
> 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:george@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
RE: Mailing List Documentation
Posted by Prescott Nasser <ge...@hotmail.com>.
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:george@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:shad@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:geobmx540@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:shad@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-subscribe@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)
RE: Mailing List Documentation
Posted by George Kinsman <ge...@georgekinsman.com>.
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:shad@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:geobmx540@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:shad@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-subscribe@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)
RE: Mailing List Documentation
Posted by Prescott Nasser <ge...@hotmail.com>.
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:shad@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:geobmx540@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:shad@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-subscribe@lucenenet.apache.org<ma...@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)
RE: Mailing List Documentation
Posted by Shad Storhaug <sh...@shadstorhaug.com>.
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:geobmx540@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:shad@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-subscribe@lucenenet.apache.org<ma...@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)
RE: Mailing List Documentation
Posted by Prescott Nasser <ge...@hotmail.com>.
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:shad@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-subscribe@lucenenet.apache.org<ma...@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)
RE: Mailing List Documentation
Posted by Shad Storhaug <sh...@shadstorhaug.com>.
> Cleaned up the subscribe page https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists
Great, thanks.
I notice that the "Current Status" (https://cwiki.apache.org/confluence/display/LUCENENET/Current+Status) used to be the same as our Contributing(https://github.com/apache/lucenenet/blob/master/CONTRIBUTING.md) page. It would be nice if there were only one place to update, as status is constantly changing (I just updated it yesterday).
-----Original Message-----
From: Prescott Nasser [mailto:geobmx540@hotmail.com]
Sent: Friday, July 7, 2017 11:21 AM
To: dev@lucenenet.apache.org
Subject: RE: Mailing List Documentation
Cleaned up the subscribe page https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists
-----Original Message-----
From: Prescott Nasser [mailto:geobmx540@hotmail.com]
Sent: Thursday, July 6, 2017 5:46 PM
To: dev@lucenenet.apache.org
Subject: RE: Mailing List Documentation
Shad -
You should have admin access to the wiki now. I will try to clean it up later tonight if you don't beat me too it.
-----Original Message-----
From: Shad Storhaug [mailto:shad@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-subscribe@lucenenet.apache.org<ma...@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)
RE: Mailing List Documentation
Posted by Prescott Nasser <ge...@hotmail.com>.
Cleaned up the subscribe page https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists
-----Original Message-----
From: Prescott Nasser [mailto:geobmx540@hotmail.com]
Sent: Thursday, July 6, 2017 5:46 PM
To: dev@lucenenet.apache.org
Subject: RE: Mailing List Documentation
Shad -
You should have admin access to the wiki now. I will try to clean it up later tonight if you don't beat me too it.
-----Original Message-----
From: Shad Storhaug [mailto:shad@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-subscribe@lucenenet.apache.org<ma...@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)
RE: Mailing List Documentation
Posted by Prescott Nasser <ge...@hotmail.com>.
Shad -
You should have admin access to the wiki now. I will try to clean it up later tonight if you don't beat me too it.
-----Original Message-----
From: Shad Storhaug [mailto:shad@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-subscribe@lucenenet.apache.org<ma...@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)