You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucenenet.apache.org by Shannon Deminick <sh...@umbraco.dk> on 2018/05/30 05:19:08 UTC

Streamlining website, docs & getting started

Hi all,

I mentioned that I would like to get the current state of the website,
documentation, getting started guide, etc... into a more usable state which
would help promote getting more contributors to the project. The current
4.8 docs project based on docfx is pretty far and can be easily updated.

I'd love to get the current website https://lucenenet.apache.org content
converted to this new format where it makes sense and I'm happy to do all
of the copy/pasting/formatting, etc... I could setup a temporary azure
website with the built docs for 4.8 and put placeholders for the content
for moving all of this info into one place so we can see how it could work.

Currently everything is quite outdated and it seems the same questions are
asked on the mail list over and over again. It would be pretty great to
have a site that isn't outdated with easy steps to get started and a
reference to what's remaining. And if the site is in the source it will be
easy for anyone to help update.

Before I start, does anyone object to me doing this?

Also some questions:

   - The wiki is based on confluence:
   https://cwiki.apache.org/confluence/display/LUCENENET/ Can we remove
   this? A lot of this info is duplicated in the docs and it seems like
   updated markdown files in the repo would be easier to contribute to than
   this other system.
   - Can i get access to the markdown source for this to make it easier to
   port over?
   - Where/how is the site https://lucenenet.apache.org hosted?
   - How is it deployed? (i.e. FTP, etc..?)

Cheers,
Shannon

Re: Streamlining website, docs & getting started

Posted by Shannon Deminick <sh...@umbraco.dk>.
OK cool, thanks for the info.

IMO having the site powered by markdown files in Git / GitHub makes the
content much easier to manage and more easily allows contribution via PRs.
There's only 5 pages making up the site currently
https://lucenenet.apache.org along with maybe a few still relevant articles
from the wiki so seems it could be pretty simple to manage with the
gitpubsub option. We can use any static site generator for this and the
output is committed/pushed to an "asf-site" branch of the repo which is
hosted. Since most file's wont change the git commit delta to this branch
would generally remain very small.

The docs site is a static site generated with docfx and doesn't need any
server side technology. I've pushed the current state of the docs site to a
temp azure website so people can see it:
https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
need to be done but overall it's OK, the discussion about it is here
https://github.com/apache/lucenenet/pull/206

I'd be happy to put together a POC for the main website using docfx since
that's what already being used for the docs generation. Of course design,
etc.. can come later (i'm no designer ;)



On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org> wrote:

> On 2018-05-30, Shannon Deminick wrote:
>
> > I mentioned that I would like to get the current state of the website,
> > documentation, getting started guide, etc... into a more usable state
> which
> > would help promote getting more contributors to the project. The current
> > 4.8 docs project based on docfx is pretty far and can be easily updated.
>
> Great.
>
> > I'd love to get the current website https://lucenenet.apache.org content
> > converted to this new format where it makes sense and I'm happy to do all
> > of the copy/pasting/formatting, etc...
>
> Please not there are a few "branding" policies an *.apache.org wesite
> has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
> I don't believe the current site is matching all requirements :-)
>
> > Before I start, does anyone object to me doing this?
>
> I'm not sure I understand the technical requirements the solution you
> are working on will impose on the website. We may need to involve infra
> if we need more than static pages in the end.
>
> > Also some questions:
>
> >    - The wiki is based on confluence:
> >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we remove
> >    this? A lot of this info is duplicated in the docs and it seems like
> >    updated markdown files in the repo would be easier to contribute to
> than
> >    this other system.
>
> Sure, we can turn off the Wiki if we no longer see any value in it.
>
> >    - Can i get access to the markdown source for this to make it easier
> to
> >    port over?
>
> I don't believe the Confluence installation is using markdown at all.
>
> >    - Where/how is the site https://lucenenet.apache.org hosted?
>
> Run on ASF infrastructure operated by our infra team.
>
> >    - How is it deployed? (i.e. FTP, etc..?)
>
> In general there are three options of hosting a *.apache.org website,
> see http://www.apache.org/dev/project-site.html .
>
> We currently use the Apache CMS which at one point in time was the
> recommended approach but no longer is. Actually the CMS uses svnpubsub
> under the covers together with a Buildbot run job that creates static
> pages from a bunch of templates. The sources for the site can be found
> at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
>
> We are free to switch from CMS to any of the alternative approaches.
>
> I haven't got any first hand experience with gitpubsub but do know
> svnpubsub as something robust. I've heard gitpubsub tends to get into
> trouble with bigger changesets, so we may need to tweak the generated
> content to not contain last modified timestamps and things like that.
>
> Stefan
>

Re: Streamlining website, docs & getting started

Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-06-05, Shannon Deminick wrote:

> I've done some work on getting a website up and running and I've used the
> theme mentioned from here https://github.com/gkinsman/LuceneNetDraftSite but
> I'm still using DocFx for this site since i think there's many benefits to
> it over just regular static sites.

This looks great, many thanks.

Stefan

Re: Streamlining website, docs & getting started

Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-06-05, Rob Vesse wrote:

> One important correction, the contributing page currently says the following:

>>    Individual Contributor License - We need this to accept any code you submit

> This is wrong! Apache only requires ICLAs from committers who have write access to Apache repositories, contributors can submit ICLAs but these are not required by the foundation.  Contributions are explicitly covered by Clause 5 of the Apache License [1]:

Rob is correct and I am probably to blame for the overzealous ICLA
requirement here - even though I cannot find this requirement in any of
our existing docs, likely haven't searched hard enough.

Different ASF communities have different standards for when they start
requiring a CLA and I happen to come from one that likes CLAs for all
significant changes.

There is no real legal requirement that would prevent us from dropping
this and rely on the Apache license terms.

Stefan

> [1]: https://www.apache.org/licenses/LICENSE-2.0.html#contributions

Re: Streamlining website, docs & getting started

Posted by Rob Vesse <rv...@dotnetrdf.org>.
New site design looks great

One important correction, the contributing page currently says the following:

   Individual Contributor License - We need this to accept any code you submit

This is wrong! Apache only requires ICLAs from committers who have write access to Apache repositories, contributors can submit ICLAs but these are not required by the foundation.  Contributions are explicitly covered by Clause 5 of the Apache License [1]:

   Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the 
   terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or 
   modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

It is pretty clear that a Pull Request meets the definition of "intentionally submitted for inclusion".  Please do not put unnecessary barriers in front of new contributors as this will only put them off!  You want to make it as easy as possible for new people to start contributing to Lucene.Net

Rob

[1]: https://www.apache.org/licenses/LICENSE-2.0.html#contributions

On 05/06/2018, 10:30, "Shannon Deminick" <sh...@umbraco.dk> wrote:

    I've done some work on getting a website up and running and I've used the
    theme mentioned from here https://github.com/gkinsman/LuceneNetDraftSite but
    I'm still using DocFx for this site since i think there's many benefits to
    it over just regular static sites. it's very easy to add additional pages
    and structure the site nicely (i.e. we can migrate the wiki here),we can
    enable search and it integrates with GitHub nicely. All this is committed
    to the docs PR https://github.com/apache/lucenenet/pull/206
    
    I've uploaded the site as it is now so people can have a look
    https://lucenenetsite.azurewebsites.net/, I'll also update the docs site to
    have the same look sometime this week.
    
    There's still a bunch needed but it's better than what is currently there. I
    think it would be better to get this live sooner than later rather than
    making this 'perfect' since the current site isn't very approachable for
    new devs. This should be pretty easy to update and deploy when needed.
    
    Some things that need to be added: A doc for helping contribute to this
    website and for the docs too, figure out how to keep the
    current download.cgi page that lists mirrors, PGP signatures, etc...   A
    page to clearly state the work remaining on 4.8 (will need to look through
    the mail archives since this info is buried in there)
    
    Let me know what you think,
    Shannon
    
    
    On Tue, Jun 5, 2018 at 12:52 AM Shannon Deminick <sh...@umbraco.dk> wrote:
    
    > Yup i recall that conversation, thanks for the reminder :) I'll start with
    > the one you've mentioned and we can go from there. Changing the design,
    > etc... should be no worries once all the data is in one place.
    >
    > On Sat, Jun 2, 2018 at 1:24 AM Shad Storhaug <sh...@shadstorhaug.com>
    > wrote:
    >
    >> Great work on the docs!
    >>
    >> > >    - The wiki is based on confluence:
    >> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
    >> remove
    >> > >    this? A lot of this info is duplicated in the docs and it seems
    >> like
    >> > >    updated markdown files in the repo would be easier to contribute to
    >> > than
    >> > >    this other system.
    >>
    >> No objection to shutting down the WIKI, but do note that some of the info
    >> doesn't exist anywhere else. We will definitely need to migrate the content
    >> from the Getting Involved section and the top 2 links from the
    >> Infrastructure section somewhere else if we shut it down (they may need
    >> some fact checking, though).
    >>
    >> > I'd be happy to put together a POC for the main website using docfx
    >> since
    >> > that's what already being used for the docs generation. Of course
    >> design,
    >> > etc.. can come later (i'm no designer ;)
    >>
    >> I am pretty happy with the look and feel that George Kinsman came up
    >> with: https://github.com/gkinsman/LuceneNetDraftSite.
    >>
    >> I started tinkering with the Logo design, but we should probably either
    >> keep the existing images, or try to get someone to contribute them. There
    >> are a lot of different logos and badge sizes that would need to be
    >> redesigned if we went with a new logo:
    >> https://github.com/apache/lucenenet/tree/master/branding/logo. But
    >> contributing new logos could be a great opportunity for a graphic designer
    >> who wants to demonstrate their skills.
    >>
    >> Also, be sure to check out last year's conversation about the web site on
    >> the mailing list. There were a lot of ideas thrown around there.
    >>
    >>
    >> https://apache.markmail.org/search/?q=lucenenet+%22new+website%22+order%3Adate-backward#query:lucenenet%20%22new%20website%22%20order%3Adate-backward+page:1+mid:td3gwv4u7mpxilkv+state:results
    >>
    >>
    >> -----Original Message-----
    >> From: Shannon Deminick [mailto:shannon@umbraco.dk]
    >> Sent: Friday, June 1, 2018 8:22 AM
    >> To: dev@lucenenet.apache.org
    >> Subject: Re: Streamlining website, docs & getting started
    >>
    >> OK cool, thanks for the info.
    >>
    >> IMO having the site powered by markdown files in Git / GitHub makes the
    >> content much easier to manage and more easily allows contribution via PRs.
    >> There's only 5 pages making up the site currently
    >> https://lucenenet.apache.org along with maybe a few still relevant
    >> articles
    >> from the wiki so seems it could be pretty simple to manage with the
    >> gitpubsub option. We can use any static site generator for this and the
    >> output is committed/pushed to an "asf-site" branch of the repo which is
    >> hosted. Since most file's wont change the git commit delta to this branch
    >> would generally remain very small.
    >>
    >> The docs site is a static site generated with docfx and doesn't need any
    >> server side technology. I've pushed the current state of the docs site to
    >> a
    >> temp azure website so people can see it:
    >> https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
    >> need to be done but overall it's OK, the discussion about it is here
    >> https://github.com/apache/lucenenet/pull/206
    >>
    >> I'd be happy to put together a POC for the main website using docfx since
    >> that's what already being used for the docs generation. Of course design,
    >> etc.. can come later (i'm no designer ;)
    >>
    >>
    >>
    >> On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org>
    >> wrote:
    >>
    >> > On 2018-05-30, Shannon Deminick wrote:
    >> >
    >> > > I mentioned that I would like to get the current state of the website,
    >> > > documentation, getting started guide, etc... into a more usable state
    >> > which
    >> > > would help promote getting more contributors to the project. The
    >> current
    >> > > 4.8 docs project based on docfx is pretty far and can be easily
    >> updated.
    >> >
    >> > Great.
    >> >
    >> > > I'd love to get the current website https://lucenenet.apache.org
    >> content
    >> > > converted to this new format where it makes sense and I'm happy to do
    >> all
    >> > > of the copy/pasting/formatting, etc...
    >> >
    >> > Please not there are a few "branding" policies an *.apache.org wesite
    >> > has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
    >> > I don't believe the current site is matching all requirements :-)
    >> >
    >> > > Before I start, does anyone object to me doing this?
    >> >
    >> > I'm not sure I understand the technical requirements the solution you
    >> > are working on will impose on the website. We may need to involve infra
    >> > if we need more than static pages in the end.
    >> >
    >> > > Also some questions:
    >> >
    >> > >    - The wiki is based on confluence:
    >> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
    >> remove
    >> > >    this? A lot of this info is duplicated in the docs and it seems
    >> like
    >> > >    updated markdown files in the repo would be easier to contribute to
    >> > than
    >> > >    this other system.
    >> >
    >> > Sure, we can turn off the Wiki if we no longer see any value in it.
    >> >
    >> > >    - Can i get access to the markdown source for this to make it
    >> easier
    >> > to
    >> > >    port over?
    >> >
    >> > I don't believe the Confluence installation is using markdown at all.
    >> >
    >> > >    - Where/how is the site https://lucenenet.apache.org hosted?
    >> >
    >> > Run on ASF infrastructure operated by our infra team.
    >> >
    >> > >    - How is it deployed? (i.e. FTP, etc..?)
    >> >
    >> > In general there are three options of hosting a *.apache.org website,
    >> > see http://www.apache.org/dev/project-site.html .
    >> >
    >> > We currently use the Apache CMS which at one point in time was the
    >> > recommended approach but no longer is. Actually the CMS uses svnpubsub
    >> > under the covers together with a Buildbot run job that creates static
    >> > pages from a bunch of templates. The sources for the site can be found
    >> > at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
    >> >
    >> > We are free to switch from CMS to any of the alternative approaches.
    >> >
    >> > I haven't got any first hand experience with gitpubsub but do know
    >> > svnpubsub as something robust. I've heard gitpubsub tends to get into
    >> > trouble with bigger changesets, so we may need to tweak the generated
    >> > content to not contain last modified timestamps and things like that.
    >> >
    >> > Stefan
    >> >
    >>
    >
    





Re: Streamlining website, docs & getting started

Posted by Arsen Shnurkov <ar...@gmail.com>.
1) this:

"Install-Package Lucene.Net -Pre "

is recipe to use with some specific package manager. Some people can use
another package managers. They feel unwelcomed at this point.

2) @"C:\Index"

is operating system specific

3) There is no way to navigate from
https://lucenenetdocs.azurewebsites.net back to
https://lucenenetsite.azurewebsites.net

4) No forums. Forums are better than mail list because former hide email
addresses.

5) On the forum there should be national sections (splitted by user's
spoken language)

6) on the page
https://lucenenetsite.azurewebsites.net/contributing/source.html
should be hyperlinks to "NLucene Architecture" and another one to
"detailed description of Source Code Repository contents"
in order to cotinue studying after downloading


05.06.2018 12:03, Shannon Deminick пишет:
> I've done some work on getting a website up and running and I've used the
> theme mentioned from here https://github.com/gkinsman/LuceneNetDraftSite but
> I'm still using DocFx for this site since i think there's many benefits to
> it over just regular static sites. it's very easy to add additional pages
> and structure the site nicely (i.e. we can migrate the wiki here),we can
> enable search and it integrates with GitHub nicely. All this is committed
> to the docs PR https://github.com/apache/lucenenet/pull/206
>
> I've uploaded the site as it is now so people can have a look
> https://lucenenetsite.azurewebsites.net/, I'll also update the docs site to
> have the same look sometime this week.
>
> There's still a bunch needed but it's better than what is currently there. I
> think it would be better to get this live sooner than later rather than
> making this 'perfect' since the current site isn't very approachable for
> new devs. This should be pretty easy to update and deploy when needed.
>
> Some things that need to be added: A doc for helping contribute to this
> website and for the docs too, figure out how to keep the
> current download.cgi page that lists mirrors, PGP signatures, etc...   A
> page to clearly state the work remaining on 4.8 (will need to look through
> the mail archives since this info is buried in there)
>
> Let me know what you think,
> Shannon
>
>
> On Tue, Jun 5, 2018 at 12:52 AM Shannon Deminick <sh...@umbraco.dk> wrote:
>
>> Yup i recall that conversation, thanks for the reminder :) I'll start with
>> the one you've mentioned and we can go from there. Changing the design,
>> etc... should be no worries once all the data is in one place.
>>
>> On Sat, Jun 2, 2018 at 1:24 AM Shad Storhaug <sh...@shadstorhaug.com>
>> wrote:
>>
>>> Great work on the docs!
>>>
>>>>>    - The wiki is based on confluence:
>>>>>    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
>>> remove
>>>>>    this? A lot of this info is duplicated in the docs and it seems
>>> like
>>>>>    updated markdown files in the repo would be easier to contribute to
>>>> than
>>>>>    this other system.
>>> No objection to shutting down the WIKI, but do note that some of the info
>>> doesn't exist anywhere else. We will definitely need to migrate the content
>>> from the Getting Involved section and the top 2 links from the
>>> Infrastructure section somewhere else if we shut it down (they may need
>>> some fact checking, though).
>>>
>>>> I'd be happy to put together a POC for the main website using docfx
>>> since
>>>> that's what already being used for the docs generation. Of course
>>> design,
>>>> etc.. can come later (i'm no designer ;)
>>> I am pretty happy with the look and feel that George Kinsman came up
>>> with: https://github.com/gkinsman/LuceneNetDraftSite.
>>>
>>> I started tinkering with the Logo design, but we should probably either
>>> keep the existing images, or try to get someone to contribute them. There
>>> are a lot of different logos and badge sizes that would need to be
>>> redesigned if we went with a new logo:
>>> https://github.com/apache/lucenenet/tree/master/branding/logo. But
>>> contributing new logos could be a great opportunity for a graphic designer
>>> who wants to demonstrate their skills.
>>>
>>> Also, be sure to check out last year's conversation about the web site on
>>> the mailing list. There were a lot of ideas thrown around there.
>>>
>>>
>>> https://apache.markmail.org/search/?q=lucenenet+%22new+website%22+order%3Adate-backward#query:lucenenet%20%22new%20website%22%20order%3Adate-backward+page:1+mid:td3gwv4u7mpxilkv+state:results
>>>
>>>
>>> -----Original Message-----
>>> From: Shannon Deminick [mailto:shannon@umbraco.dk]
>>> Sent: Friday, June 1, 2018 8:22 AM
>>> To: dev@lucenenet.apache.org
>>> Subject: Re: Streamlining website, docs & getting started
>>>
>>> OK cool, thanks for the info.
>>>
>>> IMO having the site powered by markdown files in Git / GitHub makes the
>>> content much easier to manage and more easily allows contribution via PRs.
>>> There's only 5 pages making up the site currently
>>> https://lucenenet.apache.org along with maybe a few still relevant
>>> articles
>>> from the wiki so seems it could be pretty simple to manage with the
>>> gitpubsub option. We can use any static site generator for this and the
>>> output is committed/pushed to an "asf-site" branch of the repo which is
>>> hosted. Since most file's wont change the git commit delta to this branch
>>> would generally remain very small.
>>>
>>> The docs site is a static site generated with docfx and doesn't need any
>>> server side technology. I've pushed the current state of the docs site to
>>> a
>>> temp azure website so people can see it:
>>> https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
>>> need to be done but overall it's OK, the discussion about it is here
>>> https://github.com/apache/lucenenet/pull/206
>>>
>>> I'd be happy to put together a POC for the main website using docfx since
>>> that's what already being used for the docs generation. Of course design,
>>> etc.. can come later (i'm no designer ;)
>>>
>>>
>>>
>>> On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org>
>>> wrote:
>>>
>>>> On 2018-05-30, Shannon Deminick wrote:
>>>>
>>>>> I mentioned that I would like to get the current state of the website,
>>>>> documentation, getting started guide, etc... into a more usable state
>>>> which
>>>>> would help promote getting more contributors to the project. The
>>> current
>>>>> 4.8 docs project based on docfx is pretty far and can be easily
>>> updated.
>>>> Great.
>>>>
>>>>> I'd love to get the current website https://lucenenet.apache.org
>>> content
>>>>> converted to this new format where it makes sense and I'm happy to do
>>> all
>>>>> of the copy/pasting/formatting, etc...
>>>> Please not there are a few "branding" policies an *.apache.org wesite
>>>> has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
>>>> I don't believe the current site is matching all requirements :-)
>>>>
>>>>> Before I start, does anyone object to me doing this?
>>>> I'm not sure I understand the technical requirements the solution you
>>>> are working on will impose on the website. We may need to involve infra
>>>> if we need more than static pages in the end.
>>>>
>>>>> Also some questions:
>>>>>    - The wiki is based on confluence:
>>>>>    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
>>> remove
>>>>>    this? A lot of this info is duplicated in the docs and it seems
>>> like
>>>>>    updated markdown files in the repo would be easier to contribute to
>>>> than
>>>>>    this other system.
>>>> Sure, we can turn off the Wiki if we no longer see any value in it.
>>>>
>>>>>    - Can i get access to the markdown source for this to make it
>>> easier
>>>> to
>>>>>    port over?
>>>> I don't believe the Confluence installation is using markdown at all.
>>>>
>>>>>    - Where/how is the site https://lucenenet.apache.org hosted?
>>>> Run on ASF infrastructure operated by our infra team.
>>>>
>>>>>    - How is it deployed? (i.e. FTP, etc..?)
>>>> In general there are three options of hosting a *.apache.org website,
>>>> see http://www.apache.org/dev/project-site.html .
>>>>
>>>> We currently use the Apache CMS which at one point in time was the
>>>> recommended approach but no longer is. Actually the CMS uses svnpubsub
>>>> under the covers together with a Buildbot run job that creates static
>>>> pages from a bunch of templates. The sources for the site can be found
>>>> at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
>>>>
>>>> We are free to switch from CMS to any of the alternative approaches.
>>>>
>>>> I haven't got any first hand experience with gitpubsub but do know
>>>> svnpubsub as something robust. I've heard gitpubsub tends to get into
>>>> trouble with bigger changesets, so we may need to tweak the generated
>>>> content to not contain last modified timestamps and things like that.
>>>>
>>>> Stefan
>>>>



Re: Streamlining website, docs & getting started

Posted by Shannon Deminick <sh...@umbraco.dk>.
I've done some work on getting a website up and running and I've used the
theme mentioned from here https://github.com/gkinsman/LuceneNetDraftSite but
I'm still using DocFx for this site since i think there's many benefits to
it over just regular static sites. it's very easy to add additional pages
and structure the site nicely (i.e. we can migrate the wiki here),we can
enable search and it integrates with GitHub nicely. All this is committed
to the docs PR https://github.com/apache/lucenenet/pull/206

I've uploaded the site as it is now so people can have a look
https://lucenenetsite.azurewebsites.net/, I'll also update the docs site to
have the same look sometime this week.

There's still a bunch needed but it's better than what is currently there. I
think it would be better to get this live sooner than later rather than
making this 'perfect' since the current site isn't very approachable for
new devs. This should be pretty easy to update and deploy when needed.

Some things that need to be added: A doc for helping contribute to this
website and for the docs too, figure out how to keep the
current download.cgi page that lists mirrors, PGP signatures, etc...   A
page to clearly state the work remaining on 4.8 (will need to look through
the mail archives since this info is buried in there)

Let me know what you think,
Shannon


On Tue, Jun 5, 2018 at 12:52 AM Shannon Deminick <sh...@umbraco.dk> wrote:

> Yup i recall that conversation, thanks for the reminder :) I'll start with
> the one you've mentioned and we can go from there. Changing the design,
> etc... should be no worries once all the data is in one place.
>
> On Sat, Jun 2, 2018 at 1:24 AM Shad Storhaug <sh...@shadstorhaug.com>
> wrote:
>
>> Great work on the docs!
>>
>> > >    - The wiki is based on confluence:
>> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
>> remove
>> > >    this? A lot of this info is duplicated in the docs and it seems
>> like
>> > >    updated markdown files in the repo would be easier to contribute to
>> > than
>> > >    this other system.
>>
>> No objection to shutting down the WIKI, but do note that some of the info
>> doesn't exist anywhere else. We will definitely need to migrate the content
>> from the Getting Involved section and the top 2 links from the
>> Infrastructure section somewhere else if we shut it down (they may need
>> some fact checking, though).
>>
>> > I'd be happy to put together a POC for the main website using docfx
>> since
>> > that's what already being used for the docs generation. Of course
>> design,
>> > etc.. can come later (i'm no designer ;)
>>
>> I am pretty happy with the look and feel that George Kinsman came up
>> with: https://github.com/gkinsman/LuceneNetDraftSite.
>>
>> I started tinkering with the Logo design, but we should probably either
>> keep the existing images, or try to get someone to contribute them. There
>> are a lot of different logos and badge sizes that would need to be
>> redesigned if we went with a new logo:
>> https://github.com/apache/lucenenet/tree/master/branding/logo. But
>> contributing new logos could be a great opportunity for a graphic designer
>> who wants to demonstrate their skills.
>>
>> Also, be sure to check out last year's conversation about the web site on
>> the mailing list. There were a lot of ideas thrown around there.
>>
>>
>> https://apache.markmail.org/search/?q=lucenenet+%22new+website%22+order%3Adate-backward#query:lucenenet%20%22new%20website%22%20order%3Adate-backward+page:1+mid:td3gwv4u7mpxilkv+state:results
>>
>>
>> -----Original Message-----
>> From: Shannon Deminick [mailto:shannon@umbraco.dk]
>> Sent: Friday, June 1, 2018 8:22 AM
>> To: dev@lucenenet.apache.org
>> Subject: Re: Streamlining website, docs & getting started
>>
>> OK cool, thanks for the info.
>>
>> IMO having the site powered by markdown files in Git / GitHub makes the
>> content much easier to manage and more easily allows contribution via PRs.
>> There's only 5 pages making up the site currently
>> https://lucenenet.apache.org along with maybe a few still relevant
>> articles
>> from the wiki so seems it could be pretty simple to manage with the
>> gitpubsub option. We can use any static site generator for this and the
>> output is committed/pushed to an "asf-site" branch of the repo which is
>> hosted. Since most file's wont change the git commit delta to this branch
>> would generally remain very small.
>>
>> The docs site is a static site generated with docfx and doesn't need any
>> server side technology. I've pushed the current state of the docs site to
>> a
>> temp azure website so people can see it:
>> https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
>> need to be done but overall it's OK, the discussion about it is here
>> https://github.com/apache/lucenenet/pull/206
>>
>> I'd be happy to put together a POC for the main website using docfx since
>> that's what already being used for the docs generation. Of course design,
>> etc.. can come later (i'm no designer ;)
>>
>>
>>
>> On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org>
>> wrote:
>>
>> > On 2018-05-30, Shannon Deminick wrote:
>> >
>> > > I mentioned that I would like to get the current state of the website,
>> > > documentation, getting started guide, etc... into a more usable state
>> > which
>> > > would help promote getting more contributors to the project. The
>> current
>> > > 4.8 docs project based on docfx is pretty far and can be easily
>> updated.
>> >
>> > Great.
>> >
>> > > I'd love to get the current website https://lucenenet.apache.org
>> content
>> > > converted to this new format where it makes sense and I'm happy to do
>> all
>> > > of the copy/pasting/formatting, etc...
>> >
>> > Please not there are a few "branding" policies an *.apache.org wesite
>> > has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
>> > I don't believe the current site is matching all requirements :-)
>> >
>> > > Before I start, does anyone object to me doing this?
>> >
>> > I'm not sure I understand the technical requirements the solution you
>> > are working on will impose on the website. We may need to involve infra
>> > if we need more than static pages in the end.
>> >
>> > > Also some questions:
>> >
>> > >    - The wiki is based on confluence:
>> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
>> remove
>> > >    this? A lot of this info is duplicated in the docs and it seems
>> like
>> > >    updated markdown files in the repo would be easier to contribute to
>> > than
>> > >    this other system.
>> >
>> > Sure, we can turn off the Wiki if we no longer see any value in it.
>> >
>> > >    - Can i get access to the markdown source for this to make it
>> easier
>> > to
>> > >    port over?
>> >
>> > I don't believe the Confluence installation is using markdown at all.
>> >
>> > >    - Where/how is the site https://lucenenet.apache.org hosted?
>> >
>> > Run on ASF infrastructure operated by our infra team.
>> >
>> > >    - How is it deployed? (i.e. FTP, etc..?)
>> >
>> > In general there are three options of hosting a *.apache.org website,
>> > see http://www.apache.org/dev/project-site.html .
>> >
>> > We currently use the Apache CMS which at one point in time was the
>> > recommended approach but no longer is. Actually the CMS uses svnpubsub
>> > under the covers together with a Buildbot run job that creates static
>> > pages from a bunch of templates. The sources for the site can be found
>> > at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
>> >
>> > We are free to switch from CMS to any of the alternative approaches.
>> >
>> > I haven't got any first hand experience with gitpubsub but do know
>> > svnpubsub as something robust. I've heard gitpubsub tends to get into
>> > trouble with bigger changesets, so we may need to tweak the generated
>> > content to not contain last modified timestamps and things like that.
>> >
>> > Stefan
>> >
>>
>

Re: Streamlining website, docs & getting started

Posted by Shannon Deminick <sh...@umbraco.dk>.
Yup i recall that conversation, thanks for the reminder :) I'll start with
the one you've mentioned and we can go from there. Changing the design,
etc... should be no worries once all the data is in one place.

On Sat, Jun 2, 2018 at 1:24 AM Shad Storhaug <sh...@shadstorhaug.com> wrote:

> Great work on the docs!
>
> > >    - The wiki is based on confluence:
> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
> remove
> > >    this? A lot of this info is duplicated in the docs and it seems like
> > >    updated markdown files in the repo would be easier to contribute to
> > than
> > >    this other system.
>
> No objection to shutting down the WIKI, but do note that some of the info
> doesn't exist anywhere else. We will definitely need to migrate the content
> from the Getting Involved section and the top 2 links from the
> Infrastructure section somewhere else if we shut it down (they may need
> some fact checking, though).
>
> > I'd be happy to put together a POC for the main website using docfx since
> > that's what already being used for the docs generation. Of course design,
> > etc.. can come later (i'm no designer ;)
>
> I am pretty happy with the look and feel that George Kinsman came up with:
> https://github.com/gkinsman/LuceneNetDraftSite.
>
> I started tinkering with the Logo design, but we should probably either
> keep the existing images, or try to get someone to contribute them. There
> are a lot of different logos and badge sizes that would need to be
> redesigned if we went with a new logo:
> https://github.com/apache/lucenenet/tree/master/branding/logo. But
> contributing new logos could be a great opportunity for a graphic designer
> who wants to demonstrate their skills.
>
> Also, be sure to check out last year's conversation about the web site on
> the mailing list. There were a lot of ideas thrown around there.
>
>
> https://apache.markmail.org/search/?q=lucenenet+%22new+website%22+order%3Adate-backward#query:lucenenet%20%22new%20website%22%20order%3Adate-backward+page:1+mid:td3gwv4u7mpxilkv+state:results
>
>
> -----Original Message-----
> From: Shannon Deminick [mailto:shannon@umbraco.dk]
> Sent: Friday, June 1, 2018 8:22 AM
> To: dev@lucenenet.apache.org
> Subject: Re: Streamlining website, docs & getting started
>
> OK cool, thanks for the info.
>
> IMO having the site powered by markdown files in Git / GitHub makes the
> content much easier to manage and more easily allows contribution via PRs.
> There's only 5 pages making up the site currently
> https://lucenenet.apache.org along with maybe a few still relevant
> articles
> from the wiki so seems it could be pretty simple to manage with the
> gitpubsub option. We can use any static site generator for this and the
> output is committed/pushed to an "asf-site" branch of the repo which is
> hosted. Since most file's wont change the git commit delta to this branch
> would generally remain very small.
>
> The docs site is a static site generated with docfx and doesn't need any
> server side technology. I've pushed the current state of the docs site to a
> temp azure website so people can see it:
> https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
> need to be done but overall it's OK, the discussion about it is here
> https://github.com/apache/lucenenet/pull/206
>
> I'd be happy to put together a POC for the main website using docfx since
> that's what already being used for the docs generation. Of course design,
> etc.. can come later (i'm no designer ;)
>
>
>
> On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org> wrote:
>
> > On 2018-05-30, Shannon Deminick wrote:
> >
> > > I mentioned that I would like to get the current state of the website,
> > > documentation, getting started guide, etc... into a more usable state
> > which
> > > would help promote getting more contributors to the project. The
> current
> > > 4.8 docs project based on docfx is pretty far and can be easily
> updated.
> >
> > Great.
> >
> > > I'd love to get the current website https://lucenenet.apache.org
> content
> > > converted to this new format where it makes sense and I'm happy to do
> all
> > > of the copy/pasting/formatting, etc...
> >
> > Please not there are a few "branding" policies an *.apache.org wesite
> > has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
> > I don't believe the current site is matching all requirements :-)
> >
> > > Before I start, does anyone object to me doing this?
> >
> > I'm not sure I understand the technical requirements the solution you
> > are working on will impose on the website. We may need to involve infra
> > if we need more than static pages in the end.
> >
> > > Also some questions:
> >
> > >    - The wiki is based on confluence:
> > >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we
> remove
> > >    this? A lot of this info is duplicated in the docs and it seems like
> > >    updated markdown files in the repo would be easier to contribute to
> > than
> > >    this other system.
> >
> > Sure, we can turn off the Wiki if we no longer see any value in it.
> >
> > >    - Can i get access to the markdown source for this to make it easier
> > to
> > >    port over?
> >
> > I don't believe the Confluence installation is using markdown at all.
> >
> > >    - Where/how is the site https://lucenenet.apache.org hosted?
> >
> > Run on ASF infrastructure operated by our infra team.
> >
> > >    - How is it deployed? (i.e. FTP, etc..?)
> >
> > In general there are three options of hosting a *.apache.org website,
> > see http://www.apache.org/dev/project-site.html .
> >
> > We currently use the Apache CMS which at one point in time was the
> > recommended approach but no longer is. Actually the CMS uses svnpubsub
> > under the covers together with a Buildbot run job that creates static
> > pages from a bunch of templates. The sources for the site can be found
> > at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
> >
> > We are free to switch from CMS to any of the alternative approaches.
> >
> > I haven't got any first hand experience with gitpubsub but do know
> > svnpubsub as something robust. I've heard gitpubsub tends to get into
> > trouble with bigger changesets, so we may need to tweak the generated
> > content to not contain last modified timestamps and things like that.
> >
> > Stefan
> >
>

RE: Streamlining website, docs & getting started

Posted by Shad Storhaug <sh...@shadstorhaug.com>.
Great work on the docs!

> >    - The wiki is based on confluence:
> >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we remove
> >    this? A lot of this info is duplicated in the docs and it seems like
> >    updated markdown files in the repo would be easier to contribute to
> than
> >    this other system.

No objection to shutting down the WIKI, but do note that some of the info doesn't exist anywhere else. We will definitely need to migrate the content from the Getting Involved section and the top 2 links from the Infrastructure section somewhere else if we shut it down (they may need some fact checking, though).

> I'd be happy to put together a POC for the main website using docfx since
> that's what already being used for the docs generation. Of course design,
> etc.. can come later (i'm no designer ;)

I am pretty happy with the look and feel that George Kinsman came up with: https://github.com/gkinsman/LuceneNetDraftSite.

I started tinkering with the Logo design, but we should probably either keep the existing images, or try to get someone to contribute them. There are a lot of different logos and badge sizes that would need to be redesigned if we went with a new logo: https://github.com/apache/lucenenet/tree/master/branding/logo. But contributing new logos could be a great opportunity for a graphic designer who wants to demonstrate their skills.

Also, be sure to check out last year's conversation about the web site on the mailing list. There were a lot of ideas thrown around there.

https://apache.markmail.org/search/?q=lucenenet+%22new+website%22+order%3Adate-backward#query:lucenenet%20%22new%20website%22%20order%3Adate-backward+page:1+mid:td3gwv4u7mpxilkv+state:results


-----Original Message-----
From: Shannon Deminick [mailto:shannon@umbraco.dk] 
Sent: Friday, June 1, 2018 8:22 AM
To: dev@lucenenet.apache.org
Subject: Re: Streamlining website, docs & getting started

OK cool, thanks for the info.

IMO having the site powered by markdown files in Git / GitHub makes the
content much easier to manage and more easily allows contribution via PRs.
There's only 5 pages making up the site currently
https://lucenenet.apache.org along with maybe a few still relevant articles
from the wiki so seems it could be pretty simple to manage with the
gitpubsub option. We can use any static site generator for this and the
output is committed/pushed to an "asf-site" branch of the repo which is
hosted. Since most file's wont change the git commit delta to this branch
would generally remain very small.

The docs site is a static site generated with docfx and doesn't need any
server side technology. I've pushed the current state of the docs site to a
temp azure website so people can see it:
https://lucenenetdocs.azurewebsites.net/ . There's some tweaks that still
need to be done but overall it's OK, the discussion about it is here
https://github.com/apache/lucenenet/pull/206

I'd be happy to put together a POC for the main website using docfx since
that's what already being used for the docs generation. Of course design,
etc.. can come later (i'm no designer ;)



On Wed, May 30, 2018 at 5:29 PM Stefan Bodewig <bo...@apache.org> wrote:

> On 2018-05-30, Shannon Deminick wrote:
>
> > I mentioned that I would like to get the current state of the website,
> > documentation, getting started guide, etc... into a more usable state
> which
> > would help promote getting more contributors to the project. The current
> > 4.8 docs project based on docfx is pretty far and can be easily updated.
>
> Great.
>
> > I'd love to get the current website https://lucenenet.apache.org content
> > converted to this new format where it makes sense and I'm happy to do all
> > of the copy/pasting/formatting, etc...
>
> Please not there are a few "branding" policies an *.apache.org wesite
> has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
> I don't believe the current site is matching all requirements :-)
>
> > Before I start, does anyone object to me doing this?
>
> I'm not sure I understand the technical requirements the solution you
> are working on will impose on the website. We may need to involve infra
> if we need more than static pages in the end.
>
> > Also some questions:
>
> >    - The wiki is based on confluence:
> >    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we remove
> >    this? A lot of this info is duplicated in the docs and it seems like
> >    updated markdown files in the repo would be easier to contribute to
> than
> >    this other system.
>
> Sure, we can turn off the Wiki if we no longer see any value in it.
>
> >    - Can i get access to the markdown source for this to make it easier
> to
> >    port over?
>
> I don't believe the Confluence installation is using markdown at all.
>
> >    - Where/how is the site https://lucenenet.apache.org hosted?
>
> Run on ASF infrastructure operated by our infra team.
>
> >    - How is it deployed? (i.e. FTP, etc..?)
>
> In general there are three options of hosting a *.apache.org website,
> see http://www.apache.org/dev/project-site.html .
>
> We currently use the Apache CMS which at one point in time was the
> recommended approach but no longer is. Actually the CMS uses svnpubsub
> under the covers together with a Buildbot run job that creates static
> pages from a bunch of templates. The sources for the site can be found
> at http://svn.apache.org/repos/asf/lucene.net/site/trunk/
>
> We are free to switch from CMS to any of the alternative approaches.
>
> I haven't got any first hand experience with gitpubsub but do know
> svnpubsub as something robust. I've heard gitpubsub tends to get into
> trouble with bigger changesets, so we may need to tweak the generated
> content to not contain last modified timestamps and things like that.
>
> Stefan
>

Re: Streamlining website, docs & getting started

Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-05-30, Shannon Deminick wrote:

> I mentioned that I would like to get the current state of the website,
> documentation, getting started guide, etc... into a more usable state which
> would help promote getting more contributors to the project. The current
> 4.8 docs project based on docfx is pretty far and can be easily updated.

Great.

> I'd love to get the current website https://lucenenet.apache.org content
> converted to this new format where it makes sense and I'm happy to do all
> of the copy/pasting/formatting, etc...

Please not there are a few "branding" policies an *.apache.org wesite
has to adhere to, see http://www.apache.org/foundation/marks/pmcs . TBH
I don't believe the current site is matching all requirements :-)

> Before I start, does anyone object to me doing this?

I'm not sure I understand the technical requirements the solution you
are working on will impose on the website. We may need to involve infra
if we need more than static pages in the end.

> Also some questions:

>    - The wiki is based on confluence:
>    https://cwiki.apache.org/confluence/display/LUCENENET/ Can we remove
>    this? A lot of this info is duplicated in the docs and it seems like
>    updated markdown files in the repo would be easier to contribute to than
>    this other system.

Sure, we can turn off the Wiki if we no longer see any value in it. 

>    - Can i get access to the markdown source for this to make it easier to
>    port over?

I don't believe the Confluence installation is using markdown at all.

>    - Where/how is the site https://lucenenet.apache.org hosted?

Run on ASF infrastructure operated by our infra team.

>    - How is it deployed? (i.e. FTP, etc..?)

In general there are three options of hosting a *.apache.org website,
see http://www.apache.org/dev/project-site.html .

We currently use the Apache CMS which at one point in time was the
recommended approach but no longer is. Actually the CMS uses svnpubsub
under the covers together with a Buildbot run job that creates static
pages from a bunch of templates. The sources for the site can be found
at http://svn.apache.org/repos/asf/lucene.net/site/trunk/

We are free to switch from CMS to any of the alternative approaches.

I haven't got any first hand experience with gitpubsub but do know
svnpubsub as something robust. I've heard gitpubsub tends to get into
trouble with bigger changesets, so we may need to tweak the generated
content to not contain last modified timestamps and things like that.

Stefan