Spotlight Documentation - NOT

Sounds like the complainent wants a core dump from Apple to his brain.

Life does not work that way.

So, to make the point:

 From a simple google search (spotlight site:apple.com), hardly the
domain of insider initiates, comes these results (plus 52,000+ more
-- only 37,700 were in English):


http://www.apple.com/macosx/tips/spotlight.html

http://www.apple.com/macosx/theater/spotlight.html

http://www.apple.com/downloads/macosx/spotlight/


http://developer.apple.com/macosx/spotlight.html

http://developer.apple.com/documentation/Carbon/Conceptual/
MetadataIntro/index.html

http://developer.apple.com/documentation/Carbon/Reference/
MetadataAttributesRef/index.html

http://developer.apple.com/documentation/Carbon/Conceptual/
SpotlightQuery/index.html

http://developer.apple.com/documentation/Carbon/Conceptual/
MDImporters/index.html

>Sounds like the complainent wants a core dump from Apple to his brain.

No, just reasonable documentation directly accessible from the product itself.

>From a simple google search (spotlight site:apple.com), hardly the
>domain of insider initiates, comes these results (plus 52,000+ more
>-- only 37,700 were in English):

I do not think it is in any way reasonable that I should have to do a
google search to find out how to use a product that I paid for.

At the very least, Apple could design the product and the Help System
in a way that would bring one to this information that Apple already
has about the product. And it could be indexed in a way that one
could find things easily.

On 26/5/2005 3:44 AM, "Nick Pappas" <ngpappasnii.net> spake thus:

> At the very least, Apple could design the product and the Help System
> in a way that would bring one to this information that Apple already
> has about the product.

Well as far as I know Apple Help theoretically will download new stuff from
Apple; it's certainly asked me for my proxy password in the past. Apple's
help system has gone from bad to complete crap in the last couple of years,
however. I've lost count of the number of times I've seen the "No matching
help topics were found" message, even for simple stuff. In fact, I've even
seen this message when clicking on links in Apple-supplied help!! That's
just plain useless. It's no wonder that some products implement their own
help system...

--
Nigel Stanger, Dunedin, NEW ZEALAND.
http://public.xdi.org/=nigel.stanger

On 25 May 2005, at 09:44 , Nick Pappas wrote:
>> From a simple google search (spotlight site:apple.com), hardly the
>> domain of insider initiates, comes these results (plus 52,000+ more
>> -- only 37,700 were in English):
>
> I do not think it is in any way reasonable that I should have to do a
> google search to find out how to use a product that I paid for.

Welcome to the 21st century.

For most people, spotlight is simply a field to type into. For more
advanced info, you will need to dig.

And, personally, I'd rather have had Tiger in April with little
Documentation than in August with complete and finalized documentation.

At 04:18 AM 05/26/2005 -0700, Google Kreme wrote:
>And, personally, I'd rather have had Tiger in April with little
>Documentation than in August with complete and finalized documentation.

Totally false dichotomy. Documentation can proceed in parallel with
development. In fact, in a well run development project -- heck, in a half
decently run project -- the documentation will be well under way before
coding begins. After all, the documentation is the spec. What happens when
you write code without a spec -- a thoroughly reviewed spec? Many of the
comments I've read here in the past few weeks answer that rhetorical question.

A great many software producers seem to have been duped by the argument
"most users don't read documentation so why write it". They forget to ask
how those users learn. For a great many of those users, learning consists
of asking someone more knowledgeable -- for example, someone who *does*
read documentation. So the docs remain important, even when it's only to
feed the highest level of the chain.

Edward
Art Works by Melynda Reid: http://paleo.org

On 5/27/05 09:01, "Edward Reid" <edwardpaleo.org> wrote:

>> And, personally, I'd rather have had Tiger in April with little
>> Documentation than in August with complete and finalized documentation.
>
> Totally false dichotomy. Documentation can proceed in parallel with
> development. In fact, in a well run development project -- heck, in a half
> decently run project -- the documentation will be well under way before
> coding begins. After all, the documentation is the spec. What happens when
> you write code without a spec -- a thoroughly reviewed spec? Many of the
> comments I've read here in the past few weeks answer that rhetorical question.

The rough drafts can. But the fine points, which are far more work than most
people think, cannot.

The only documentation that can work off the spec and be done as coding is
done and NOT require extensive work once the GM is done are headers. If
you're writing user docs, you have to test procedures, you have to have good
screen shots, and you can't do but about 20% of that until the product is
done.

Note, by 'user' docs I mean everything that isn't header docs for
programmers.

--
John C. Welch Writer/Analyst
Bynkii.com Mac and other opinions
jwelchbynkii.com

On or about 5/27/05 7:01 AM, thus spake "Edward Reid" <edwardpaleo.org>:

> At 04:18 AM 05/26/2005 -0700, Google Kreme wrote:
>> And, personally, I'd rather have had Tiger in April with little
>> Documentation than in August with complete and finalized documentation.
>
> Totally false dichotomy. Documentation can proceed in parallel with
> development. In fact, in a well run development project -- heck, in a half
> decently run project -- the documentation will be well under way before
> coding begins. After all, the documentation is the spec.

The documentation is not the spec. But Edward is right in this sense: the
attempt to explain and justify something in rational terms to the end-user
in plain language can and, in real life, often does illuminate areas of the
project's behavior that are irrational or unjustifiable, strongly suggesting
the need for a revision of the spec. I have found (and I believe so has
Adam) that on projects where I have written the documentation, my efforts
(read "complaints") have ultimately had a profound effect upon the project
itself. If someone at Apple had tried to explain in plain words, as to an
intelligent end-user, how Spotlight behaves, his inevitable cries of "This
is nuts!" would (one hopes!) have sent the engineers scuttling back to the
drawing board. m.

--
matt neuburg, phd = matttidbits.com, http://www.tidbits.com/matt/
pantes anthropoi tou eidenai oregontai phusei
AppleScript: the Definitive Guide! NOW SHIPPING...! (Finally.)
http://www.amazon.com/exec/obidos/ASIN/0596005571/somethingsbymatt
Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/

On 5/27/05 12:58 PM, "Matt Neuburg" <matttidbits.com> wrote:

> The documentation is not the spec. But Edward is right in this sense: the
> attempt to explain and justify something in rational terms to the end-user
> in plain language can and, in real life, often does illuminate areas of the
> project's behavior that are irrational or unjustifiable, strongly suggesting
> the need for a revision of the spec.

I have known shops where the user documentation was done first (with room
for input of the "we can't do that" sort), and then the working spec was
produced from that. I found it to work wonderfully well.

But that was back in the days of 18-month software cycles (and actual QA
departments), not 18-hour ones.

NCR in the late 60s and the 70s didn't work that way...there was a series of
refinements to the technical spec (with the user interaction gurus watching
and "helping"), cleverly called A-spec [the document you initially sold the
project to the software review board with] through B-, C-, D-, E- and
F-spec.] The F-spec and the software went to the user documentation writers
in Dayton (who almost always did a bang-up job) who finished the user docs
during the last 6 months (9 months early in the period) of testing by the
development shop and Dayton's Software QA operation (also darn good).

These days, of course, except for large industrial and government jobs, the
software is obsolete in those 18 months.

  --John

On May 27, 2005, John C. Welch wrote,
>The only documentation that can work off the spec and be done as coding is
>done and NOT require extensive work once the GM is done are headers. If
>you're writing user docs, you have to test procedures, you have to have good
>screen shots, and you can't do but about 20% of that until the product is
>done.

Not true. Test procedures should be written from the software
specifications, totally independent of the coding process, by test
specialists. If that can't be done, then the specs are incomplete
and/or the development process is faulty. If you don't know what the
software is supposed to do, you can't test it, and you can't be
confident that it's free of errors. (In fact, you can't even define
what an error is!) Specs which exist only in coders' heads are
almost worthless. (Exception: single-person shops where the product
is small enough that the developer can keep the whole thing in his
head. That's a tangent I won't follow right now.)

Likewise, documentation should be written from the specs (at least to
a first draft level), totally independent of the coding and testing
processes, by documentation specialists. If done right, this also
validates the consistency and usability of the specs, including user
interface aspects.

I'm not asserting that the specs have to be 100% complete before
coding starts. But in order to work from incomplete specs (e.g.,
using an iterative or evolutionary design & development model), the
whole set of parallel work processes must be very carefully managed
so that feedback and cross-feed work together.

It's true that you can't get "live" screen shots until the software
is running. But part of the process of developing test procedures is
defining what the screen shots _should_ look like based on the specs.
Besides, screen shots are not documentation - they are the
illustrations that may (or may not) accompany documention.

In my opinion, a really good manager of software development will
utilize the documentation process to help insure that the final
product is of the highest possible quality. In view of what this
thread has said about the lack of documentation for Spotlight, I
conclude that Apple may be just as short of really good software
development managers as Microsoft and many other software companies
are.

Carl
Senior Systems Analyst,
formerly a test witness for mil-spec software critical to flight safety

On 5/29/05 21:57, "Carl S. Zimmerman" <csz_stlswbell.net> wrote:

> It's true that you can't get "live" screen shots until the software
> is running. But part of the process of developing test procedures is
> defining what the screen shots _should_ look like based on the specs.
> Besides, screen shots are not documentation - they are the
> illustrations that may (or may not) accompany documention.

Untrue. Screen shots are critical to good documentation. They provide an
unambiguous visual reference as to what you're talking about. Snapz Pro and
some good annotated screenshots are better examples of what needs to be done
than any ten pages of spec-based writing.

john

--
John C. Welch Writer/Analyst
Bynkii.com Mac and other opinions
jwelchbynkii.com