As long as I'm talking about possible improvements I'd like to work on:

Anyone else have an itch to dump moin moin for confluence? I've used both, and I think that confluence is just far superior.

Also, moin moin has a very dated look, and it's hard to make modern looking wiki pages - confluence looks much more modern in general, and its just easier to do most things. This is something I've been thinking about for a couple years now.

Getting a confluence wiki seems as simple as opening an infra JIRA. I think I've seen there may be some ways to transfer content as well. Perhaps someone else knows more. But even if there is not, I'd be for a manual migration (and would contribute towards that). There are other issues around old links and what not, but I think others have made this move, so perhaps there are acceptable ways to mitigate that pain?

- Mark Miller
lucidimagination.com


---------------------------------------------------------------------

On 02/07/2012 09:09 PM, Mark Miller wrote:
> As long as I'm talking about possible improvements I'd like to work on:
>
> Anyone else have an itch to dump moin moin for confluence? I've used both, and I think that confluence is just far superior.
>
> Also, moin moin has a very dated look, and it's hard to make modern looking wiki pages - confluence looks much more modern in general, and its just easier to do most things. This is something I've been thinking about for a couple years now.
>
> Getting a confluence wiki seems as simple as opening an infra JIRA. I think I've seen there may be some ways to transfer content as well. Perhaps someone else knows more. But even if there is not, I'd be for a manual migration (and would contribute towards that). There are other issues around old links and what not, but I think others have made this move, so perhaps there are acceptable ways to mitigate that pain?
>
> - Mark Miller
> lucidimagination.com
>
>
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
I can't speak directly from experience with confluence, but it looks more professional and modern in comparison to moin moin. I could help with the manual migration if need.
--
Joe Cabrera
---------------------------------------------------------------------

+1 for confluence!
But I don't know how we can easily move the moin moin content to confluence...

Martijn

On 8 February 2012 04:28, Joe Cabrera <[EMAIL PROTECTED]> wrote:
> On 02/07/2012 09:09 PM, Mark Miller wrote:
>>
>> As long as I'm talking about possible improvements I'd like to work on:
>>
>> Anyone else have an itch to dump moin moin for confluence? I've used both,
>> and I think that confluence is just far superior.
>>
>> Also, moin moin has a very dated look, and it's hard to make modern
>> looking wiki pages - confluence looks much more modern in general, and its
>> just easier to do most things. This is something I've been thinking about
>> for a couple years now.
>>
>> Getting a confluence wiki seems as simple as opening an infra JIRA. I
>> think I've seen there may be some ways to transfer content as well. Perhaps
>> someone else knows more. But even if there is not, I'd be for a manual
>> migration (and would contribute towards that). There are other issues around
>> old links and what not, but I think others have made this move, so perhaps
>> there are acceptable ways to mitigate that pain?
>>
>> - Mark Miller
>> lucidimagination.com
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [EMAIL PROTECTED]
>> For additional commands, e-mail: [EMAIL PROTECTED]
>>
> I can't speak directly from experience with confluence, but it looks more
> professional and modern in comparison to moin moin. I could help with the
> manual migration if need.
>
>
> --
> Joe Cabrera
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>

--
Met vriendelijke groet,

Martijn van Groningen

---------------------------------------------------------------------

Ryan had started on it some time ago, but was never completed.  One of the nice things about Confluence is you can skin it to look similar to the website.  In fact, for Mahout, we've done exactly that.  I think there are some scripts to automate the migration.

FWIW, I also think we should think about re-organizing some of our docs so that it is easier for beginners to get started and also to have a lot more of it be a reference manual.  This goes for both Lucene and Solr.

On Feb 7, 2012, at 10:09 PM, Mark Miller wrote:

> As long as I'm talking about possible improvements I'd like to work on:
>
> Anyone else have an itch to dump moin moin for confluence? I've used both, and I think that confluence is just far superior.
>
> Also, moin moin has a very dated look, and it's hard to make modern looking wiki pages - confluence looks much more modern in general, and its just easier to do most things. This is something I've been thinking about for a couple years now.
>
> Getting a confluence wiki seems as simple as opening an infra JIRA. I think I've seen there may be some ways to transfer content as well. Perhaps someone else knows more. But even if there is not, I'd be for a manual migration (and would contribute towards that). There are other issues around old links and what not, but I think others have made this move, so perhaps there are acceptable ways to mitigate that pain?
>
> - Mark Miller
> lucidimagination.com
>
>
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>

--------------------------------------------
Grant Ingersoll
http://www.lucidimagination.com

Well, at least some people have tried this:
https://studio.plugins.atlassian.com/wiki/display/UWC/UWC+MoinMoin+Notes
https://studio.plugins.atlassian.com/wiki/display/UWC/Universal+Wiki+Converter

Looks at a quick glance that the conversion might be hit-or-miss, but
if it worked...
On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
> Ryan had started on it some time ago, but was never completed.  One of the
> nice things about Confluence is you can skin it to look similar to the
> website.  In fact, for Mahout, we've done exactly that.  I think there are
> some scripts to automate the migration.
>
> FWIW, I also think we should think about re-organizing some of our docs so
> that it is easier for beginners to get started and also to have a lot more
> of it be a reference manual.  This goes for both Lucene and Solr.
>
> On Feb 7, 2012, at 10:09 PM, Mark Miller wrote:
>
> As long as I'm talking about possible improvements I'd like to work on:
>
> Anyone else have an itch to dump moin moin for confluence? I've used both,
> and I think that confluence is just far superior.
>
> Also, moin moin has a very dated look, and it's hard to make modern looking
> wiki pages - confluence looks much more modern in general, and its just
> easier to do most things. This is something I've been thinking about for a
> couple years now.
>
> Getting a confluence wiki seems as simple as opening an infra JIRA. I think
> I've seen there may be some ways to transfer content as well. Perhaps
> someone else knows more. But even if there is not, I'd be for a manual
> migration (and would contribute towards that). There are other issues around
> old links and what not, but I think others have made this move, so perhaps
> there are acceptable ways to mitigate that pain?
>
> - Mark Miller
> lucidimagination.com
>
>
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>
> --------------------------------------------
> Grant Ingersoll
> http://www.lucidimagination.com
>
>
>

---------------------------------------------------------------------

On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
> Ryan had started on it some time ago, but was never completed.

I thought that was maybe for the website, but not the wiki (I don't
think we have a wiki space created yet?)

> FWIW, I also think we should think about re-organizing some of our docs so
> that it is easier for beginners

+1

Specific to Solr, I think we should drop all the "back compat" in our
documentation and target it toward 4.0

-Yonik
lucidimagination.com

---------------------------------------------------------------------

We should also consider having part of the wiki "committers only" (or
others that we decide to give access).  Just as with our code
development, it doesn't always make sense to completely crowd-source
documentation.

-Yonik
lucidimagination.com

On Wed, Feb 8, 2012 at 9:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>> Ryan had started on it some time ago, but was never completed.
>
> I thought that was maybe for the website, but not the wiki (I don't
> think we have a wiki space created yet?)
>
>> FWIW, I also think we should think about re-organizing some of our docs so
>> that it is easier for beginners
>
> +1
>
> Specific to Solr, I think we should drop all the "back compat" in our
> documentation and target it toward 4.0
>
> -Yonik
> lucidimagination.com

---------------------------------------------------------------------

On Wed, Feb 8, 2012 at 6:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>> Ryan had started on it some time ago, but was never completed.
>
> I thought that was maybe for the website, but not the wiki (I don't
> think we have a wiki space created yet?)
>

I was looking at it as a replacement for our forrest site:
https://cwiki.apache.org/SOLRxSITE/

+1 to convert MoinMoin

ryan

---------------------------------------------------------------------

+1

We could have a section of the Wiki named SolrPedia serving as a high-quality structured reference manual. Confluence allows templates for easier authoring of these. There could be a "Concept" template, a "Component" template, a "HowTo" template...

I think we could leave it open to all registered Confluence users and lock things down later if necessary.

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com
Solr Training - www.solrtraining.com

On 8. feb. 2012, at 22:21, Ryan McKinley wrote:

> On Wed, Feb 8, 2012 at 6:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
>> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>>> Ryan had started on it some time ago, but was never completed.
>>
>> I thought that was maybe for the website, but not the wiki (I don't
>> think we have a wiki space created yet?)
>>
>
> I was looking at it as a replacement for our forrest site:
> https://cwiki.apache.org/SOLRxSITE/
>
> +1 to convert MoinMoin
>
> ryan
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
---------------------------------------------------------------------

FWIW: i have almost no opinion at all on what wiki software we use, but
that really just seems like the seed of this conversation...

: Specific to Solr, I think we should drop all the "back compat" in our
: documentation and target it toward 4.0

In an ideal world, i think the best way to organize all of this stuff
would be...
1) "official documentation" (even solr user level, non-javadoc type
information) would be live in the source tree and branched/packaged with
each release, so every user has a copy of the docs that affect them.

2) "official documentation" for the last N versions would be snapshoted on
the website

3) the wiki would be solely for "unofficial documentation" (ie: faq, tips
and tricks, recepies).  it would be world editable, and we could be very
ruthless about pruning away info that only applies to old releases so that
the only "version specific caveats" we'd have to deal with would be any
subtleties between bug fix versions (ie: 3.6.2, vs 4.2 vs trunk as a
hypothetical example) -- users of older versions would have the complete
"official documentation" and they could always look through the wiki page
history arround the date of their versions release to see what
tips/ticks/caveats might have been listed back then.

4) The "official documentation" should liberaly and judiciously link out
to the "unofficial documentation" with boilerplate links like "More info
about this [feature|class|module|plugin|etc...] may be found <a
href='${wikiurl}'>on the wiki</a>" ... even if $wikiurl doesn't exist at
the time of writing, so that users who want to contribute tips/tricks
about a particular feature/class/module/plugin/etc.. have a ready made
place to do so.
Now, having said that, i have no idea how to sanely migrate from the world
we live in today to that ideal world (even if everyone agreed it would be
ideal).  

For solr user documentation about plugins, i sort of started down this
road once upon a time with SOLR-555, but it fell by the way side since
there didn't seem to be much interest from other people in helping to
polish it up and start taking advantage of it (particularly since there
would be a lot of initial work to migrate the param info into the new
javadoclet tags that i did not have the energy to deal with by myself).  
Even if we had that and all the javadocs were perfect and all the params
were documented perfectly, it wouldn't help us with things like the solr
tutorial or any of the other forrest generated docs for lucene-core users
which we also need to think about.

There's also the issue of dealing with users of older versions ... if we
magically pushed a button and had the perfect line between "official
documentation" and "unofficial documentation" that i mentioned above for
4.0, i'd still be leary of prunning the solr wiki of info about older
versions because users of those older versions wouldn't have any
"official" documentation for themselves. (time travel is hard)

Coming full circle...

If there is an ideal world, and we all agreed about what it looks like,
and a concentrated effort is made to make that ideal world a reality,
then perhaps switching wiki software might actually be a good way to deal
with the problem of legacy users:

 a) create newer/better "official documentation" (somewhere)
 b) create new confluence wikis for "unofficial documentation"
    contributed by users
 c) make the existing moinmoin wikis read only with a big caveat
    at the top that they contain historic information for users
    of old versions of lucene/solr and users of new versions
    should instead link to {a} and {b}

-Hoss

---------------------------------------------------------------------

On Feb 8, 2012, at 7:35 AM, Yonik Seeley wrote:

> We should also consider having part of the wiki "committers only" (or
> others that we decide to give access).  Just as with our code
> development, it doesn't always make sense to completely crowd-source
> documentation.

I could see that we move "official docs" to the CMS and leave the wiki for new things, etc. and for user generated recipes, etc.

I'm having a discussion on site-dev@ about how we might be able to incorporate some type of commenting system (disqus, perhaps) into the CMS so that we can have people comment on CMS pages -- assuming we put up a more coherent ref. guide there.

>
> -Yonik
> lucidimagination.com
>
>
>
> On Wed, Feb 8, 2012 at 9:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
>> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>>> Ryan had started on it some time ago, but was never completed.
>>
>> I thought that was maybe for the website, but not the wiki (I don't
>> think we have a wiki space created yet?)
>>
>>> FWIW, I also think we should think about re-organizing some of our docs so
>>> that it is easier for beginners
>>
>> +1
>>
>> Specific to Solr, I think we should drop all the "back compat" in our
>> documentation and target it toward 4.0
>>
>> -Yonik
>> lucidimagination.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>

--------------------------------------------
Grant Ingersoll
http://www.lucidimagination.com

I think that's a popular and superior model - committers have access and users can leave comments. If that means we start making committers out of heavy doc helpers, that seems like a plus to me.

On Feb 9, 2012, at 3:48 PM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:

>
> On Feb 8, 2012, at 7:35 AM, Yonik Seeley wrote:
>
>> We should also consider having part of the wiki "committers only" (or
>> others that we decide to give access).  Just as with our code
>> development, it doesn't always make sense to completely crowd-source
>> documentation.
>
> I could see that we move "official docs" to the CMS and leave the wiki for new things, etc. and for user generated recipes, etc.
>
> I'm having a discussion on site-dev@ about how we might be able to incorporate some type of commenting system (disqus, perhaps) into the CMS so that we can have people comment on CMS pages -- assuming we put up a more coherent ref. guide there.
>
>>
>> -Yonik
>> lucidimagination.com
>>
>>
>>
>> On Wed, Feb 8, 2012 at 9:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
>>> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>>>> Ryan had started on it some time ago, but was never completed.
>>>
>>> I thought that was maybe for the website, but not the wiki (I don't
>>> think we have a wiki space created yet?)
>>>
>>>> FWIW, I also think we should think about re-organizing some of our docs so
>>>> that it is easier for beginners
>>>
>>> +1
>>>
>>> Specific to Solr, I think we should drop all the "back compat" in our
>>> documentation and target it toward 4.0
>>>
>>> -Yonik
>>> lucidimagination.com
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [EMAIL PROTECTED]
>> For additional commands, e-mail: [EMAIL PROTECTED]
>>
>
> --------------------------------------------
> Grant Ingersoll
> http://www.lucidimagination.com
>
>
>

Couldn't the wiki be the home of comments, barring any other technology being a better solution?  Simply provide a link to the wiki page with the same name as the CMS page.  

Erik

On Feb 9, 2012, at 15:58 , Mark Miller wrote:

> I think that's a popular and superior model - committers have access and users can leave comments. If that means we start making committers out of heavy doc helpers, that seems like a plus to me.
>
> On Feb 9, 2012, at 3:48 PM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>
>>
>> On Feb 8, 2012, at 7:35 AM, Yonik Seeley wrote:
>>
>>> We should also consider having part of the wiki "committers only" (or
>>> others that we decide to give access).  Just as with our code
>>> development, it doesn't always make sense to completely crowd-source
>>> documentation.
>>
>> I could see that we move "official docs" to the CMS and leave the wiki for new things, etc. and for user generated recipes, etc.
>>
>> I'm having a discussion on site-dev@ about how we might be able to incorporate some type of commenting system (disqus, perhaps) into the CMS so that we can have people comment on CMS pages -- assuming we put up a more coherent ref. guide there.
>>
>>>
>>> -Yonik
>>> lucidimagination.com
>>>
>>>
>>>
>>> On Wed, Feb 8, 2012 at 9:38 AM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
>>>> On Wed, Feb 8, 2012 at 6:17 AM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>>>>> Ryan had started on it some time ago, but was never completed.
>>>>
>>>> I thought that was maybe for the website, but not the wiki (I don't
>>>> think we have a wiki space created yet?)
>>>>
>>>>> FWIW, I also think we should think about re-organizing some of our docs so
>>>>> that it is easier for beginners
>>>>
>>>> +1
>>>>
>>>> Specific to Solr, I think we should drop all the "back compat" in our
>>>> documentation and target it toward 4.0
>>>>
>>>> -Yonik
>>>> lucidimagination.com
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [EMAIL PROTECTED]
>>> For additional commands, e-mail: [EMAIL PROTECTED]
>>>
>>
>> --------------------------------------------
>> Grant Ingersoll
>> http://www.lucidimagination.com
>>
>>
>>
---------------------------------------------------------------------

On Thu, Feb 9, 2012 at 3:48 PM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
> I could see that we move "official docs" to the CMS and leave the wiki for
> new things, etc. and for user generated recipes, etc.

Why wouldn't these be orthogonal decisions (assuming confluence can
support permissions):
a) what CMS/Wiki to use (ASF or confluence)
b) who should be able to change what

I haven't used the ASF CMS yet, so I don't know how it stacks up
compared to confluence.

-Yonik
lucidimagination.com

---------------------------------------------------------------------

On Feb 9, 2012, at 3:57 PM, Yonik Seeley wrote:

> On Thu, Feb 9, 2012 at 3:48 PM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
>> I could see that we move "official docs" to the CMS and leave the wiki for
>> new things, etc. and for user generated recipes, etc.
>
> Why wouldn't these be orthogonal decisions (assuming confluence can
> support permissions):
> a) what CMS/Wiki to use (ASF or confluence)
> b) who should be able to change what
>

Sure.  I was mainly getting at that I think it would be nice if we promoted docs as "official" and they were on the main site.

> I haven't used the ASF CMS yet, so I don't know how it stacks up
> compared to confluence.

My main issue w/ Confluence for docs is the ASF insists on using the Auto Export plugin b/c they don't want people hitting the main wiki for some reason (performance, I guess).  But the AutoExport thingy is buggy, doesn't look as nice and infra has also indicated they don't want people using that anymore either, at least that is what I seem to recall.

See the diff between:
https://cwiki.apache.org/confluence/display/MAHOUT/Mahout+Wiki

https://cwiki.apache.org/MAHOUT/mahout-wiki.html

The first one is the proper confluence site w/ Look and Feel we added.  The second is the auto-export and it is what you get when you search on Google, etc.

See https://cwiki.apache.org/CWIKI/
"The first rule of CWIKI is don't link to CWIKI! This Confluence site is autoexported to HTML. Please link only to the exported pages. Do not link directly to the wiki! The autoexport includes live links to allow easy editing of pages. By linking to the autoexport, we can scale the site for everyone's benefit."

On Thu, Feb 9, 2012 at 3:48 PM, Grant Ingersoll <[EMAIL PROTECTED]> wrote:
> I could see that we move "official docs" to the CMS and leave the wiki for
> new things, etc. and for user generated recipes, etc.

OK, so how about this for Solr documentation on the website:
pseudo-versioned live docs.

The docs for 4x live under
solr/4 or solr/doc/4

These docs wouldn't be strictly versioned... we would continue
updating the docs as needed after a release.
We also would not need to bump the version number for every minor
release... we can do as we do on the wiki now and note that a new
feature was added in 4.1 for example (but we can drop everything that
only applies to 3x and below).  I think this can result in some of the
highest quality documentation with the least amount of effort.

A different question is whether these docs should be included in a
release.  IMO that's not needed (and creates extra maintenance work in
our build scripts, puts extra burden on release managers, etc).

-Yonik
lucidimagination.com

---------------------------------------------------------------------

: OK, so how about this for Solr documentation on the website:
: pseudo-versioned live docs.
:
: The docs for 4x live under
: solr/4 or solr/doc/4
:
: These docs wouldn't be strictly versioned... we would continue
: updating the docs as needed after a release.
...
: A different question is whether these docs should be included in a
: release.  IMO that's not needed (and creates extra maintenance work in
: our build scripts, puts extra burden on release managers, etc).

just to be clear, you are suggesting that the canonical, authoritative
source version of hte documentation would be part of the website (under
"https://svn.apache.org/repos/asf/lucene/cms/trunk) in markdown format,
editbale via the CMS; and that these docs wouldn't be "branched and
versioned" in the same way as releases, we'd just have a "4" directory
side by side with a "3" (or "5" directory) in the same "trunk" of the
website source dir.

essentially this inverts the idea of "versioned" docs as we've thought of
it in the past -- instead of keeping the docs in svn along with the src
code, and copying a "snapshot" to the live site when we release, we'd have
continously living breathing versions of the docs for each branch that are
canonically part of hte site, and those could be snapshoted when a release
is cut.

(personally i think including snapshots of at least the raw markdown
version of the docs in each release tar ball is critically important --
but i recognize that this could easily be a question scripting an
automation and should be orthoginal to the question of where these docs
live canonically and how they are edited)

I'm suprised at how little i hate this idea.

The biggest concern i have is still about encouraging documentation
contributions from the community.  With the forrest based docs, it wasn't
"trivial" for a user to help improve the docs, but it was at least
straightforward on anyplatform that supported java, and the inclusion of
the source docs in the main trunk of code development ment anyone hacking
hte code could easily hack the docs as well.  Asking people who want t
ocontribute to the documentation to check out another svn working dir
probably isn't hte end of the world -- but we have to find a way to make
testing local doc builds easier and less error prone for this to be
viable.
-Hoss

---------------------------------------------------------------------