Re: Documentation: target audience [long]

[Joan M Carroll <jc...@world.std.com>]

> I agree - certainly there's no reason to have it biased towards
> windows.  My thought was to try to make it "bias-free" to the extent possible.

my 2 cents:

first let me shamelessly say that i am bi-platform.  whew.  glad to
come clean with *that:->

can't say i'm bias-free though.

tho i have resisted win1.0 and every subsequent win version
(still preferring dos, university *nix, or just about anything else),
my desktop has always been and probably will always be windoze.  can't
help it - i have to make a living in fin svcs.  HOWEVER, my service
platform will NEVER be windoze.  imho anyone running substantial
OSS-serviceware on win - for public consumption - is in denial.  i
believe there are 12 step programs for this.

xindice is a net-based service.  even thought it is very nice and
convenient for those of us who can play with it on our windoze boxes,
or use it for a *nix sanity check, i wouldn't spend equivalent
efforts promoting win usage.

where OSS is concerned, win is a better client than server. yeah yeah
i hear all the microshaft grumblers in the background....  it's
just my opinion.  the software will be where u left it in the A.M...

truly i think that any extra effort s.b. channelled into supporting
current OS standards and models.  i for 1 can live w/out perfect win
versions of OSS service modules.  the heart-breaking thing is an OSS
apps/service that doesn't support vert/horiz OSS stds (you all know
the X*'s of which i speak).  thorough & rigorous standards support is a
big draw

my nice-to-have list would include more i18n/L10n awareness.  just by
way of example, i think the forrest tool should *design-in*
resourcing of text ... e.g. multi-lingual site gen is just tranlating
a file.  i know, this is a different project.  but this is an example
of how sometimes the really significant product design objectives can
get lost in the shuffle.  the avg non-native-english speaking person
wanting to help globalise the site will have a 23+Mb download to use
the forrest tool.  then the fun will start.

i view the standards-respectors and the int'l community as the really
key end-users.  As Vladimir noted, the performance archetype is not
Oracle (yet:-).  i think the high-impact indiv contributors in the
global, stds-focused talent pool have the tools to help Xindice
transition to that level though.  the contributors on this list are a
good example

to sum up:
i think bias is ok.  the platforms are not the same, the performance is
not the same, plus many - great - OSS projects have inherent "win drag"
such as requiring cgywin, or feature forks (eg php), or just plain
poor win performance/support (java apps like netbeans, even expensive
commercial solutions like togethersoft very easily nail a win box).
same can be said if you wanted to grind down into *nix'es (alpha, solaris,
os/x etc).

if you check out the php manual, it is the indiv contributors who
usually document the win "features" (bugs/workarounds).  the doc makes
relatively little mention of code forks/impl differences.

> No, I don't think so at all.  As I said, I just think it makes sense to
> leave unsaid what needn't be said.  By providing great linux docs, along
> with good windows docs as well, you've covered your bases without saying

agreed.  everything in scope s.b. as high-quality as resources permit.
vladimir has asked for win contributors, and it is up to all of us to
make win quality happen.

> But hey - you are putting in the hours working on all this - that gives you
> right.  It's those of us who just come in to voice our opinions who need to
> be more careful how we word things!  :)

word!

> Yep - agreed - the main thing is to not do it in an alienating or
> condescending way (especially since there's no reason to).  And I'm not

don't worry, we win users have been paying $$$ to be alienated for DECADES
i think the earlier point (from Ahmed?) is well-taken: if you're
offering code & a working app for the cost of a download, you will
really have to use harsh language like 'deny host' to get rid of us

> when it would fit on two floppies!  :)  I love linux.  And some will say,

agreed - & 1 tomsrtbt floppy can still bootstrap just about anything

> As for screenshots: why not have different platforms?  Many great projects

agreed - shell cmd screenshots for admin etc s.b. platform-indep

ultimately xindice is storing documents, and sooner or later this means
browser:

Snapshots of browsers -  how about compliant browsers with standard DOM?
s.b. same browser(s) used for core testing of doc, demo, etc...

mozilla, galeon, etc come to mind (& could probably use the exposure).
Konqueror?  Opera?  at this moment i just say no.  but that's just me

i know what i have read and experienced w different browsers, but i
can't say that i know where the best stds-compliance may be found.

Demo - A browser-based demo should support relevant web stds, but
probably has to be tested to support - egads - MSIE4+ based upon
sheer mkt penetration.  I think we have all had potential clients
go away & never return when the demo breaks the browser.  again, the
'any browser' model is a good goal ... though 'any browser' may not
give a @#$ about XML derived formats ... it still should be possible
to use server-side logic to force 'thunking down' to std html for any
browser

RE: Documentation: target audience

[Joan M Carroll <jc...@world.std.com>]

On Mon, 25 Nov 2002, Dave Viner wrote:

> Since I've contributed a bunch of windows-y stuff in recent days, I just
> wanted to share my opinion briefly.

i think this is a case-in-point... it is really up to the user base
to ensure the quality - regardless of the platform.  you are saying
it - and doing it.  i think (i hope) we're all on the same page about this

at the moment - if there were sides - the win side would be ahead
based upon your 'howto' submissions.  i am raising a pint to you
as i type.  it's all good.  if we were all as conscientious, how
we parcel out scarce resources would be a non-issue.

my experience with xindice1.0 was that it performed better on linux
than win.  the scripts were better, there were fewer assertions etc.
this did not aggrevate me, because

1) i realize that OSS projects are resource-constrained, so if something
doesn't work, i need to be prepared to 'put-up or shut-up' to deal
with my specific problem.

In this regard, i think *this* list has been absolutely friendly to all
contributions (not all communities are - i can attest to that)

2) i don't use win for OSS network services

if i did use win as a service platform, i would have
invested more time in working out the problems (i did actually
do a total re-vamp of the DOS batch scripts.  in the process i
remembered what a dinosaur DOS is, and how many OS limitations exist.
DOS has no official 'maintainer', so one must always use only the
most primitive assumptions about the builtin/command support)

In the interest of (my) shutting up:->, i am 'putting up' a couple
of doc revisions.  i am attaching documentation.tar of

1) compilation.xml  - minor typo fix (thanks to dave for the other chg,
you beat me to it...)

2) related.xml - minor addition to solicit users to send links for
their xindice-based applications

3) documentation.xml.diffs - diffs log


i will also do my best to fill-in the linux "fix-me's" in the
documentation already submitted ... so pls standby  NOTE: if
someone else is already working on this, please post a NOTICE!...and
i'll get out another pint to raise to you too while i slave over
something else:-)

cheers!
j

RE: Documentation: target audience

[Dave Viner <dv...@yahoo-inc.com>]

Since I've contributed a bunch of windows-y stuff in recent days, I just
wanted to share my opinion briefly.

I agree with Jim, we should make Xindice the best Open Source Native XML
database.  And, in my opinion, we need as many users as possible to help
improve our product.  Whether our users are windows folks or unix folks,
they are Xindice users.  To me, that's the important point.  We are
fostering a Xindice user community.  That doesn't speak one iota about their
prefered operating system.  And in fact, I think that our community will be
stronger if there are more operating systems.  So I think our documentation
should appeal to as many operating system users as possible, within reason.
To me, this means that we should have complete documentation for windows and
unix users.  I have used a few open source projects whose docs were
completely unix oriented.  For me, this is a big problem since most of my
prototyping is on windows.

However, I also think we should present information in a consistent way.
Consistency in documentation helps users find what they are looking for more
quickly.  And it reflects a level of professionalism in the product that
helps to mollify concerned employers.  I've seen technical managers reject
several open source products simply because the documentation was
disorganized, incomplete, and extremely sloppy.  I'm not suggesting that
those decisions were correct, but I am suggesting that we can all help
Xindice avoid those types of problems by producing clear, concise, and
helpful documentation that reflects the level of professionalism evident in
the product's core code.

Anyway, those are just my thoughts.  I hope to continue contributing more
documentation and refining the parts I've added so far!  Hopefully at some
point in the future, we can all raise a pint to celebrate our contributions
that will have made the best open source xml database out there !

dave


-----Original Message-----
From: Joan M Carroll [mailto:jcarroll@world.std.com]
Sent: Friday, November 22, 2002 8:51 PM
To: xindice-dev@xml.apache.org
Subject: Re: Documentation: target audience [long]


> I agree - certainly there's no reason to have it biased towards
> windows.  My thought was to try to make it "bias-free" to the extent
possible.

my 2 cents:

first let me shamelessly say that i am bi-platform.  whew.  glad to
come clean with *that:->

can't say i'm bias-free though.

tho i have resisted win1.0 and every subsequent win version
(still preferring dos, university *nix, or just about anything else),
my desktop has always been and probably will always be windoze.  can't
help it - i have to make a living in fin svcs.  HOWEVER, my service
platform will NEVER be windoze.  imho anyone running substantial
OSS-serviceware on win - for public consumption - is in denial.  i
believe there are 12 step programs for this.

xindice is a net-based service.  even thought it is very nice and
convenient for those of us who can play with it on our windoze boxes,
or use it for a *nix sanity check, i wouldn't spend equivalent
efforts promoting win usage.

where OSS is concerned, win is a better client than server. yeah yeah
i hear all the microshaft grumblers in the background....  it's
just my opinion.  the software will be where u left it in the A.M...

truly i think that any extra effort s.b. channelled into supporting
current OS standards and models.  i for 1 can live w/out perfect win
versions of OSS service modules.  the heart-breaking thing is an OSS
apps/service that doesn't support vert/horiz OSS stds (you all know
the X*'s of which i speak).  thorough & rigorous standards support is a
big draw

my nice-to-have list would include more i18n/L10n awareness.  just by
way of example, i think the forrest tool should *design-in*
resourcing of text ... e.g. multi-lingual site gen is just tranlating
a file.  i know, this is a different project.  but this is an example
of how sometimes the really significant product design objectives can
get lost in the shuffle.  the avg non-native-english speaking person
wanting to help globalise the site will have a 23+Mb download to use
the forrest tool.  then the fun will start.

i view the standards-respectors and the int'l community as the really
key end-users.  As Vladimir noted, the performance archetype is not
Oracle (yet:-).  i think the high-impact indiv contributors in the
global, stds-focused talent pool have the tools to help Xindice
transition to that level though.  the contributors on this list are a
good example

to sum up:
i think bias is ok.  the platforms are not the same, the performance is
not the same, plus many - great - OSS projects have inherent "win drag"
such as requiring cgywin, or feature forks (eg php), or just plain
poor win performance/support (java apps like netbeans, even expensive
commercial solutions like togethersoft very easily nail a win box).
same can be said if you wanted to grind down into *nix'es (alpha, solaris,
os/x etc).

if you check out the php manual, it is the indiv contributors who
usually document the win "features" (bugs/workarounds).  the doc makes
relatively little mention of code forks/impl differences.

> No, I don't think so at all.  As I said, I just think it makes sense to
> leave unsaid what needn't be said.  By providing great linux docs, along
> with good windows docs as well, you've covered your bases without saying

agreed.  everything in scope s.b. as high-quality as resources permit.
vladimir has asked for win contributors, and it is up to all of us to
make win quality happen.

> But hey - you are putting in the hours working on all this - that gives
you
> right.  It's those of us who just come in to voice our opinions who need
to
> be more careful how we word things!  :)

word!

> Yep - agreed - the main thing is to not do it in an alienating or
> condescending way (especially since there's no reason to).  And I'm not

don't worry, we win users have been paying $$$ to be alienated for DECADES
i think the earlier point (from Ahmed?) is well-taken: if you're
offering code & a working app for the cost of a download, you will
really have to use harsh language like 'deny host' to get rid of us

> when it would fit on two floppies!  :)  I love linux.  And some will say,

agreed - & 1 tomsrtbt floppy can still bootstrap just about anything

> As for screenshots: why not have different platforms?  Many great projects

agreed - shell cmd screenshots for admin etc s.b. platform-indep

ultimately xindice is storing documents, and sooner or later this means
browser:

Snapshots of browsers -  how about compliant browsers with standard DOM?
s.b. same browser(s) used for core testing of doc, demo, etc...

mozilla, galeon, etc come to mind (& could probably use the exposure).
Konqueror?  Opera?  at this moment i just say no.  but that's just me

i know what i have read and experienced w different browsers, but i
can't say that i know where the best stds-compliance may be found.

Demo - A browser-based demo should support relevant web stds, but
probably has to be tested to support - egads - MSIE4+ based upon
sheer mkt penetration.  I think we have all had potential clients
go away & never return when the demo breaks the browser.  again, the
'any browser' model is a good goal ... though 'any browser' may not
give a @#$ about XML derived formats ... it still should be possible
to use server-side logic to force 'thunking down' to std html for any
browser