[jira] [Commented] (SOLR-4618) Integrate LucidWorks' Solr Reference Guide with Solr documentation

["Hoss Man (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-4618?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13671881#comment-13671881 ] 

Hoss Man commented on SOLR-4618:
--------------------------------

Ok, well ... i'm not sure what happened, but I definitely had an update for this issue that I wrote up ~week ago which I aparently never hit submit on or something, so i'm going to try to re-create it.  It was mostly responses to specific comments/questions people had asked so far in the issue...

h4. On the general topic of using Confluence to maintain this documentation

bq. Apache version of software is a full release behind the latest. They are not planning to move and/or use Solr as a chance to test the latest version?

ASF uses a single confluence istance for all projects, I don't think we should plan/assume/hope for any specific upgrade of confluence in any of our plans -- is there something specific in the latest version of confluence that you had in mind that you are asking about?

bq. Have anyone considered storing doc in SVN alongside the code. 

This is something that's been discussed/tried in the past, but it has proven problematic...

* For "user" documentation like this, keeping the docs along side the code isn't as easy as it is for "developer" docs where you leverage tools like javadocs -- the structure of the desired user documentation doesn't neccessarily match the structure of the code
* Most of the Solr developers i've heard express an opinion on maintaining docs in svn vs maintaing docs as a wiki UI seem to prefer using a wiki -- the level of conviction on these sorts of opinions tends to increase when you remember that wiki software automatically solves the "geneating site" aspects for you; as opposed to something like using docbook, or XSLT transformed xhtml files or what not.
* In particular, it's worth learning from the past: the entire solr website use to be managed by a forrest script that generated HTML from docbook files and was bundled into every release.  It was in fact exactly what you describe: a set of docs along side the source code in svn that could be versioned along with releases -- and yet ... except for the tutorial page it got very little love from committers.  New "formal" docs were (almost) never added, instad the wiki was considered a preferable place to document things because it was easier to deal with.  What has been talked about here is essentially the best of both worlds: using hte wiki for easy editing/management of the docs by committers, with the ability to version/release PDF snapshots.

bq. But it could be a thing to consider with Wiki pages stored in GitHub as a standalone project and then generated into static and fast content using something like MiddleMan

An approach like that would not be viable as a method for maintining any documentation we wanted to officially publish and release as an apache project -- the authoritative copy needs to be kept on apache infrastructure.


h4. On comments...

bq. Comments are not terribly big thing on the Solr Wiki. Most of them are more like call to action/bug reports. ...


I was thinking the same thing about comments not being super important when i wrote my last update, but the key thing to remember (in comparisong to the existing wiki) is that since we plan to publish this doc as part of our release, we need to use a model where only the committers can edit the doc itself.  Moving forward comments become very important as the primary means for users to provide feedback on the document or point out corrections that need to be made.

bq. ...Maybe integrating external (e.g. Disqus) module is sufficient?

I also started down the path to looking into a service like Disqus, but I had reservations about depending on an extenal system like that -- then I discovered the ASF INFRA team already offers a similar type service for ASF projects, and based on my reading, I think this looks like it will work great for our usecases...

* Info: https://comments.apache.org/help.html
* Example on the tomcat docs: http://tomcat.apache.org/tomcat-7.0-doc/windows-service-howto.html#comments_section

bq. The relevant info posted into the comments will pass to the official doc? Some time read a thread with 200 comments to find the right answer is annoying. The relevant info should will be merge to the doc in future versions of the document

Because of the licensing rules arround what we as a project "release" comments must _not_ be included in the published version of the doc, nor would we want them to be -- as you said, relevent info shold be rolled up into the doc itself, and older comments that are no longer relevant should gradualy be removed.


h4. On cwiki vs moinmoin and the future of wiki.apache.org/solr

bq. Is the goal to merge content or to replace it? I think Wikis overlap, but I am not sure about one being a superset for another.

There is no strict superset.  In my opinion the original goal for the moinmoin wiki still remains the same as the day it was created: a place for the community as a whole to be able to create and collaborate on free-form content about solr.  It's just that we as developer/scommitters have been abusuing it for years in place of publishing true, formal, official documentation.

The focus here in this Jira is about getting this refrence guide online as "official" documentation.  Once that's done, there is likeley a *lot* of content in the existing MoinMoin wiki that can be purged, and replaced with links into the new official refrence guide, but that certainly doesn't mean all of MoinMoin content should go away or be migrated into the ref guide

Some concrete examples:  
* The ref guide is a great place to list of every configuration option and their valid values, but the community MoinMoin wiki is still a good place for "tips and tricks" about combining various config options to solve example problems.  
* Some pages just flat out would not make sense as part of the Solr refrence guide (ie: PublicServers, NightlyBuilds, CommitterInfo, etc...)
* Some pages _might_ make sense in the ref guide, but would probably be better as external community edit pages that are linked to from the ref guide (ie: SolrResources, FAQ, SolrPerformanceData, SolrRelevancyCookbook, etc...)

bq. Let's kill MoinMoin by making it read-only with big warnings that this is out-of-date. ...

As yonik mentioned, there are so many existing links, killing the MoinMoin wiki as a whole seems like a bad idea.  Killing entire pages also seems like a bad idea for the same reason.  I think we should instead purge content from pages where it's redundent, linking from MoinMoin to the new ref guide pages on the same topic when doing so, and (where appropriate) keep existing "tips and tricks" type content on those MoinMoin pages

bq. ... Can't we simply create a separate Confluence Space which is open for editing by whoever?

We probably could, but that seems like a completley distinct discussion that can happen later.  For now, i really want to focus solely on getting this ref guide content live and in a usable & maintainable state where it can be snapshooted and published with each release.  There still needs to be a community wiki, and if after we get the ref guide live folks would like to push for replacing MoinMoin with Confluence for the community wiki i certainly won't object -- but that should be tracked in a distinct issue.

----

Ok ... i think that catches me up with what i thought i already posted.

My new, new, update is that in talking with cassandra, I think I've figured out the steps we need to get the ZIP imported into CWIKI _and_ deal with the ASF specific CWIKI stuff to make it play nice with the autoexporter.  I also learned that cassandra has been maintaining the LucidWorks copy of the ref guide while waiting for progress on this issue, and should soon (or maybe already?) have a 4.3 version she can attach and we can start with that.

Since i'm (clearly) getting lost in this issue as it stands right now, i'm going to open Sub-Tasks to track the concrete actions that need to be taken moving forwrad to help keep them straight, and to help isolate the import steps so i can get the INFRA team to review them and hopefully give their blessing (i don't think that's stricly needed, pretty sure i have all the neccessary confluence perms already, but i'd rather be safe)...

                
> Integrate LucidWorks' Solr Reference Guide with Solr documentation
> ------------------------------------------------------------------
>
>                 Key: SOLR-4618
>                 URL: https://issues.apache.org/jira/browse/SOLR-4618
>             Project: Solr
>          Issue Type: Improvement
>          Components: documentation
>    Affects Versions: 4.1
>            Reporter: Cassandra Targett
>            Assignee: Hoss Man
>         Attachments: NewSolrStyle.css, SolrRefGuide4.1-ASF.zip
>
>
> LucidWorks would like to donate the "Apache Solr Reference Guide", maintained by LucidWorks tech writers, to the Solr community. It was first produced in 2009 as a download-only PDF for Solr 1.4, but since 2011 it has been online at http://docs.lucidworks.com/display/solr/ and updated for Solr 3.x releases and for Solr 4.0 and 4.1.
> I've prepared an XML export from our Confluence installation, which can be easily imported into the Apache Confluence installation by someone with system admin rights. The doc has not yet been updated for 4.2, so it covers Solr 4.1 so far. I'll add some additional technical notes about the export itself in a comment. 
> Since we use Confluence at LucidWorks, I can also offer assistance getting Confluence set up, importing this package into it, or any other help needed for the community to start using this. 

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org