Some wiki cleanup thoughts

[Chris Hostetter <ho...@fucit.org>]

i've been thinking that there are some little things that could be done to 
clean the wiki up a bit, i'm happy to do them but i wanted to send out a 
quick ping before i spend a chunk of time on it in case someone thinks 
it's a bad idea...

1) find all usages of stuff like [Solr 1.2+], [Solr1.2], [Solr 1.3] that 
denote when a feature/param was added and change them to...

    <!>["Solr1.2"]            (or 1.3 as needed)

...the <!> will insert an "attention" icon to help people notice them, 
and the quotes will force MoinMoin to make a link out of hte text (Solr1.2 
isn't a very MoinMoin friendly wiki word)

2) gut the contents of the Solr1.2 (it still has a bunch of pre 1.2 
release planning) and replace it with a page explaining when 1.2 was 
released, where to find it, and a blurb explaining that any links to this 
page are used to indicate a feature that was added in this release.

3) add a Solr1.3 page with a similar blurb about how it denotes a feature 
that *should* be added in 1.3)

(making these pages and using links instead of just text will make it 
eaier down the road to find them and remove them ... when we're up to Solr 
2.0 we don't really need to draw attention to features added in 1.2)

4) create MoinMoin "Categories" for things like RequestHandlers and 
ResponseWriters (the MoinMoin editing screen gies you a pulldown to assign 
pages to categories when editing them) .. put all of the RequestHandler and 
ResponseWriter pages in the appropriate category, and change various 
places (ie: FrontPage) to use the macro for listing all pages in a 
category so we don't have to maintain the list manually.


objections?


-Hoss

Re: Some wiki cleanup thoughts

[Chris Hostetter <ho...@fucit.org>]

: I think a way to version the Wiki at the time of release would be really
: helpful.  I know it isn't directly related to this task, but I think it would
: be really useful to have archives of the Wiki, since it is the main

Eh ... i'm not sure i agree with you on that one.  i've always wished we 
could bundle the wiki with the releases but (as you know) there are legal 
issues beyond the solvable technical ones.

having online "archival" views of the wiki almost strikes me as the worst 
of both worlds ... you have to be online to read it, but you don't gain 
any wisdom from updates after the release.  if there was a feature in 1.2 
that had a bug in it, but you were looking at the online archived 1.2 
version of the wiki, you may not notice the big red flashing text warning 
you about a potential problem.

while i wasn't that hot on the whole [Solr 1.2] syntax when people first 
started using it (because it seemed like it would be a nightmare to clean 
up after a few versions) it's definitely grown on me as a way for the wiki 
to always document the most current info, with little icons signifying 
important things to know if you are using specific versions ... but 
skimming info about newer versions can still be useful as (if for no other 
reason then to tell you about all the cool features you could have if you 
upgraded)

The key is just to be consistent and methodical about annotating when 
stuff is available ... and in the long run, cleaning up annotations that 
are so old as to not be relevant.


-Hoss

Re: Some wiki cleanup thoughts

[Grant Ingersoll <gs...@apache.org>]

On Sep 5, 2007, at 6:29 PM, Chris Hostetter wrote:

>
> i've been thinking that there are some little things that could be  
> done to clean the wiki up a bit, i'm happy to do them but i wanted  
> to send out a quick ping before i spend a chunk of time on it in  
> case someone thinks it's a bad idea...
>
> 1) find all usages of stuff like [Solr 1.2+], [Solr1.2], [Solr 1.3]  
> that denote when a feature/param was added and change them to...
>
>    <!>["Solr1.2"]            (or 1.3 as needed)
>
> ...the <!> will insert an "attention" icon to help people notice  
> them, and the quotes will force MoinMoin to make a link out of hte  
> text (Solr1.2 isn't a very MoinMoin friendly wiki word)

I think a way to version the Wiki at the time of release would be  
really helpful.  I know it isn't directly related to this task, but I  
think it would be really useful to have archives of the Wiki, since  
it is the main documentation for Solr, at the time of release.  I  
know we can't package it with the release (search the legal-discuss  
or java-user archives for reason), but it would be good to somehow  
host it and then link to it from the release docs.

-Grant

Re: Some wiki cleanup thoughts

[Chris Hostetter <ho...@fucit.org>]

: I think the Response Writer section is still a little rough, given that some
: of the wiki pages listed there are also listed in the IntegratingSolr

you know ... i didn't even notice that when i did it.

: category.  Is it worthwhile creating new pages e.g. JSONResponseWriter and
: putting the response writer related content from SolJSON into it (and
: similar for SolRuby & SolPython)?  I think it would make the section
: clearer.  What does everyone think?

go for it.  It definitely makes sense for there to be a pages specific to 
the response writers, seperate from the pages specific to the languages, 
where notes about communicating with Solr from clients written in those 
languages can refer to any useful response writters)

(allthough this means we probably want to rename SolJSON to SolrAJAX ... 
but that doesn't seem like a big problem)


-Hoss

Re: Some wiki cleanup thoughts

[Pieter Berkel <pi...@gmail.com>]

I think these wiki changes are positive, I've been meaning to create a page
for the new PHP response writers introduced in SOLR-196 but haven't had time
yet.

I think the Response Writer section is still a little rough, given that some
of the wiki pages listed there are also listed in the IntegratingSolr
category.  Is it worthwhile creating new pages e.g. JSONResponseWriter and
putting the response writer related content from SolJSON into it (and
similar for SolRuby & SolPython)?  I think it would make the section
clearer.  What does everyone think?

Piete


On 06/09/07, Chris Hostetter <ho...@fucit.org> wrote:

> I've done 1, 2, and 3 below.  i also started on #4, doing just
> QueryResponseWriters.  It may be my imagination (or it may be unlreated)
> but pages seem slower at the moment .. os before i add categories for
> other things ... i'm going to let it soak for a few days and see if it's
> my imagination.
>
>

Re: Some wiki cleanup thoughts

[Chris Hostetter <ho...@fucit.org>]

I've done 1, 2, and 3 below.  i also started on #4, doing just 
QueryResponseWriters.  It may be my imagination (or it may be unlreated) 
but pages seem slower at the moment .. os before i add categories for 
other things ... i'm going to let it soak for a few days and see if it's 
my imagination.


: 1) find all usages of stuff like [Solr 1.2+], [Solr1.2], [Solr 1.3] that
: denote when a feature/param was added and change them to...
: 
:    <!>["Solr1.2"]            (or 1.3 as needed)
: 
: ...the <!> will insert an "attention" icon to help people notice them, and the
: quotes will force MoinMoin to make a link out of hte text (Solr1.2 isn't a
: very MoinMoin friendly wiki word)
: 
: 2) gut the contents of the Solr1.2 (it still has a bunch of pre 1.2 release
: planning) and replace it with a page explaining when 1.2 was released, where
: to find it, and a blurb explaining that any links to this page are used to
: indicate a feature that was added in this release.
: 
: 3) add a Solr1.3 page with a similar blurb about how it denotes a feature that
: *should* be added in 1.3)
: 
: (making these pages and using links instead of just text will make it eaier
: down the road to find them and remove them ... when we're up to Solr 2.0 we
: don't really need to draw attention to features added in 1.2)
: 
: 4) create MoinMoin "Categories" for things like RequestHandlers and
: ResponseWriters (the MoinMoin editing screen gies you a pulldown to assign
: pages to categories when editing them) .. put all of the RequestHandler and
: ResponseWriter pages in the appropriate category, and change various places
: (ie: FrontPage) to use the macro for listing all pages in a category so we
: don't have to maintain the list manually.



-Hoss

Re: Some wiki cleanup thoughts

[Erik Hatcher <er...@ehatchersolutions.com>]

On Sep 5, 2007, at 8:22 PM, Chris Hostetter wrote:
> : I was considering adding quite a few pages for the solrsharp  
> project.  Any
> : specific requests for where new content should go?
>
> Flare set a good example by using subpages...
>
>   "Flare" gives you an overview
>   "Flare/Goals" has Goals
>   "Flare/ToDo" has todo ... etc.
>
> It lets you have pages with general names that don't over pollute the
> main namespace.  there are also macros to make it easy to navigate  
> arround
> subpages with a common parent...
>
> http://wiki.apache.org/solr/ 
> HelpOnMacros#head-3bd981f061f262d3605935dfe29519d9be970487
>
> ...one thing Flare doesn't use but could is the Search macro to  
> generate a
> numbered list of all subpages...
>
> 	[[FullSearch(title:"Flare/")]]
>
> ...since i'm not really involved in Flare, i don't feel comfortable
> changing that ... but you could do it for SolrSharp pages.  (i'm  
> about to
> do something similar with other "top level" pages)

Thanks for the tip, Hoss.  I've replaced the list of pages on the  
main Flare page with that, much more (self) maintainable!

I'd really be pleased to see our wiki broken into subpages more.  I'm  
still trying to convince myself that editing wikis is fun.  A  
<textarea> without the simplest of cmd-F find capability frustrates  
regularly.  More pages organized into nested divisions, less text per  
page is where I lean.

	Erik

Re: Some wiki cleanup thoughts

[Chris Hostetter <ho...@fucit.org>]

: I was considering adding quite a few pages for the solrsharp project.  Any
: specific requests for where new content should go?

Flare set a good example by using subpages...

  "Flare" gives you an overview
  "Flare/Goals" has Goals
  "Flare/ToDo" has todo ... etc.

It lets you have pages with general names that don't over pollute the 
main namespace.  there are also macros to make it easy to navigate arround 
subpages with a common parent...

http://wiki.apache.org/solr/HelpOnMacros#head-3bd981f061f262d3605935dfe29519d9be970487

...one thing Flare doesn't use but could is the Search macro to generate a 
numbered list of all subpages...

	[[FullSearch(title:"Flare/")]]

...since i'm not really involved in Flare, i don't feel comfortable 
changing that ... but you could do it for SolrSharp pages.  (i'm about to 
do something similar with other "top level" pages)


-Hoss

Re: Some wiki cleanup thoughts

[Jeff Rodenburg <je...@gmail.com>]

I was considering adding quite a few pages for the solrsharp project.  Any
specific requests for where new content should go?

-- j

On 9/5/07, Chris Hostetter <ho...@fucit.org> wrote:
>
>
> i've been thinking that there are some little things that could be done to
> clean the wiki up a bit, i'm happy to do them but i wanted to send out a
> quick ping before i spend a chunk of time on it in case someone thinks
> it's a bad idea...
>
> 1) find all usages of stuff like [Solr 1.2+], [Solr1.2], [Solr 1.3] that
> denote when a feature/param was added and change them to...
>
>     <!>["Solr1.2"]            (or 1.3 as needed)
>
> ...the <!> will insert an "attention" icon to help people notice them,
> and the quotes will force MoinMoin to make a link out of hte text (Solr1.2
> isn't a very MoinMoin friendly wiki word)
>
> 2) gut the contents of the Solr1.2 (it still has a bunch of pre 1.2
> release planning) and replace it with a page explaining when 1.2 was
> released, where to find it, and a blurb explaining that any links to this
> page are used to indicate a feature that was added in this release.
>
> 3) add a Solr1.3 page with a similar blurb about how it denotes a feature
> that *should* be added in 1.3)
>
> (making these pages and using links instead of just text will make it
> eaier down the road to find them and remove them ... when we're up to Solr
> 2.0 we don't really need to draw attention to features added in 1.2)
>
> 4) create MoinMoin "Categories" for things like RequestHandlers and
> ResponseWriters (the MoinMoin editing screen gies you a pulldown to assign
> pages to categories when editing them) .. put all of the RequestHandler
> and
> ResponseWriter pages in the appropriate category, and change various
> places (ie: FrontPage) to use the macro for listing all pages in a
> category so we don't have to maintain the list manually.
>
>
> objections?
>
>
> -Hoss
>
>

Re: Some wiki cleanup thoughts

[Ryan McKinley <ry...@gmail.com>]

  >
> objections?
> 

It all sounds good to me!

ryan