: Before looking too hard at the links (will later):
Maybe i wasn't explicitly clear enough about what i was trying to focus on
-- but then again, maybe if you'd looked at the links i had provided it
would have been implicitly clear enough :)
Both of your comments are accurate and good suggestions for general
*improvements* to the ref guide -- i encourage you to either open
jiras, or comment on the appropriate pages, with suggested edits.
But what you are talking about are "nice to have" improvements.
What i'm more immediately concerned with, and what i'm focusing on with
this audit & the linked edits that i'm asking for feedback on, are things
that *MUST* be changed in the ref guide prior to publishing the 5.0
version, because the current versions of the pages in question are
fundementally broken and give false information regarding the things
mention in the subject of this email:
a) solr is no longer a war
- any page that talks about wars, webapps, servlet containers, etc.
is now wrong.
- any page discussing the installation / management of solr as a
webapp is now wrong.
- any page talking about installing solr that doesn't mention the
"server" directory is now wrong.
b) the example directory changes:
- there is now more then 1 solr example, so we have to be specific -
any page refering to "THE solr example" is missleading and vague.
- many "example/..." paths mentioned in the ref guide no longer exist
c) the creation of bin/solr
- this is now the recomended/suported way to run solr and any mention
of running solr in the ref guide must be updated to refer to it
- all mentions of running the example(s) need to refer to the
appropraite "-e foo" command
d) sample solr urls with collection1 or an implicit default collection
- any URL, particularly the "example" urls that doesn't have a
collection name in it which corrisponds to the collection name
created by the corrisponding "bin/solr -e foo" example command (if
the page assumes one) is wrong and won't make sense to any new
users who read the guide
"a" above generally maps to "#1" in my original email (below) and the
first section (Things that Users will/should expect in the docs) of the
linked doc...
https://cwiki.apache.org/confluence/display/solr/INTERNAL+-+5.0+Ref+Guide+Overhaul+Notes#INTERNAL-5.0RefGuideOverhaulNotes-ThingsthatUserswill/shouldexpectinthedocs
...i'm setting that aside for the moment and trying to focus on "b,c,d"
which map to "#2" in my original mail.
The point here is not just to think about general ways we can make the ref
guide better given new features & improvements in solr -- we should always
be thinking about that in every version of the ref guide, but we can also
make those cahnges at any time.
The point here is to ensure that we correctly fix any documentation
that has become flat out *WRONG* as a result of these changes to the
structure of the solr release.
: > 1) the "big" areas we need to make sure we cover related to installation
: > 2) an audit of all pages that are impacted to *any* degree by these changes
: >
: >
https://cwiki.apache.org/confluence/display/solr/INTERNAL+-+5.0+Ref+Guide+Overhaul+Notes
: >
: > #1 is certainly important, and I hope folks who have been a lot more
: > involved with the new /server/ structure and getting rid of the war (*cough*
: > tim *cough* miller) can step in and help direct those aspects of
: > documentation.
: >
: >
: > But in this email i'd like to focus on #2 since it's going to involve a lot
: > of fiddling with a *lot* of different.
: >
: > This type of work is ripe for for parallelization and diving up among a lot
: > of people -- but only if there is a clear understanding of what types of
: > edits are needed and what sort of pattern/model those edits should follow.
: >
: > I've taken a stab at "fixing" 5 sample pages from the ref guide to try and
: > show what i had in mind. I've linked not only to those 5 pages but also the
: > specific edits (so it's hopefully easy to see what's going on) in a box
: > labeled "Hoss'ss Proof Of Concenpt for edits" ...
: >
: >
https://cwiki.apache.org/confluence/display/solr/INTERNAL+-+5.0+Ref+Guide+Overhaul+Notes#INTERNAL-5.0RefGuideOverhaulNotes-Thingstoauditindepth...
: >
: >
: > ... I'd appreciate feedback from folks on whether you think this is the
: > right direction to head in before I (or anyone else) try to dive in and do a
: > bunch of cleanup.
-Hoss
http://www.lucidworks.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
