lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Parkes" <steven_par...@esseff.org>
Subject RE: commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo
Date Sat, 24 Feb 2007 01:42:46 GMT
All wiki changes.

-----Original Message-----
From: Grant Ingersoll [mailto:gsingers@apache.org] 
Sent: Friday, February 23, 2007 2:04 PM
To: java-dev@lucene.apache.org
Subject: Re: commited docs vs wiki -- was: Re: [jira] Commented:
(LUCENE-805) New Lucene Demo

I'll ask on infrastructure if there is a way to take a snapshot of  
the Wiki as HTML for release purposes.  If we can do that, then I  
think we could move more to the Wiki.  One solution, would be to have  
a simple script that calls wget (or some crawler) and downloads all  
of the wiki.  It would, however, be better if the wiki supported  
tagging a snapshot.  I've seen flashes of references on other  
projects about the Confluence wiki from Atlassian.  Is this available  
for use at Apache and does it have the features we want?

Also, FWIW, I just updated the release page on the Wiki and it said:
---
	Thank you for your changes. Your attention to detail is
appreciated.

	Status of sending notification mails:
	[en] DanielNaber, StevenParkes, : Mail sent OK
---
Do these two really receive all the wiki change notification emails  
or are they just subscribed to this particular page?

-Grant


On Feb 19, 2007, at 9:25 PM, Chris Hostetter wrote:

>
> : Yeah, query-syntax is pretty static, so that would be fine, but I
> : sense a slippery slope here.  Scoring is static, too, but I think if
> : people want to add to the scoring doc, that would be fine.  Part of
> : me feels like it should be all the docs, including the file  
> formats b/
> : c we are trying to encourage people to document.  On the other hand,
> : some parts of the docs, like the file formats and query-syntax, feel
> : more in stone to me and I can see a case that they should only be
> : changed through a patch approach so that a committer is reviewing  
> the
>
> i'm with you all the way on that one ... it seems like every day i  
> change
> my mind about how important it is to have "official" documentation  
> vs wiki
> documentation.
>
> when solr first entered incubation, most of our stuff went in the wiki
> just because it seemed like the easiest way to get feedback,
> improvements, and copy-editing from the widest audience ... we  
> discussed
> migrating docs into subversion once they were more fleshed out, but  
> now
> we're looking at migrating more docs from subversion to the wiki  
> then we
> are the other direction.
>
> for Lucene-Java i'd be really leary of things like fileformats,
> querystynax, and scoring just being wiki pages ... people still ask
> questions about the fileformat from lucene 1.4.2, or how scoring  
> worked in
> 1.2 ... if the only history of thta info was in a wiki where you  
> had to
> figure out the right historic version that lined up with your code  
> based
> on date stamps of commits (because we'd want to update the doc when  
> hte
> change was commited, not when the release was made)
>
> the killer solution to a lot of problems would be a good utility for
> slurping the whole wiki into html files, with all of hte wiki links  
> *and*
> all of the links from the wiki to the "site" being translated into
> relative file paths as an automated part of hte release.
>
> the only other anoyance i have about the wiki that wouldn't be  
> solved with
> something like thta is the "javadoc annotation missing feature"  
> problem of
> the wiki ... some things really belong in javadocs, but you still  
> want to
> allow users to easily annoate those docs with their own tips/tricks  
> about
> using it ... stuff that's deliniated as not being formal  
> documentation,
> but still good to keep in mind, ie:
>    http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters
>
> PHP.net set the gold standard for this years ago...
>    http://www.php.net/manual/en/language.oop5.basic.php
>
> ...and Perl's CPAN is making progress...
>   http://www.annocpan.org/~AREIBENS/PDF-API2-0.57/lib/PDF/ 
> API2.pm#note_1389
>
> ... but i've never seen a good Javadoc appraoch to this problem,  
> and none
> of these solutions really address the issue of "releasing" baked  
> versions
> of hte documentation that include the annotations/tips ... you'd  
> have to
> commit them as part of the formal docs)
>
> : wiki policy to notify java-dev or java-commits when there are
> : changes?  I'm not sure how the wiki is administered or if I'm  
> missing
> : the notifications already.
>
> i believe wiki edits already go to the commits list (that's how we set
> Solr up anyway)
>
>
>
>
> -Hoss
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>

--------------------------
Grant Ingersoll
Center for Natural Language Processing
http://www.cnlp.org

Read the Lucene Java FAQ at http://wiki.apache.org/jakarta-lucene/ 
LuceneFAQ



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


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


Mime
View raw message