Documentation on expressions??

[Jan Schenkel]

--- Geoff Caplan <geoff at advantae.com> wrote:
> Jan,
> 
> JS> section hosts very interesting information
> JS> - the mailing list archives can be searched at
> JS> <http://mindlube.com/cgi-bin/search-use-rev.cgi>
> 
> That's good to know. So why the **** don't RunRev
> link to it from
> their archive page??
> 

Well the list manager auto-generates all those html
pages ; however, a direct link from the website, or
better yet a transfer of the entire technology, would
go a long way.

> JS> For people who are just starting out, Dan Shafer
> has
> JS> written an excellent book (volume 1 available,
> more on
> JS> the way, published through Revolution Press)
> JS>
> <http://www.runrev.com/resources/shaferbook.shtml>
> 
> This would be the next step, if I decide to go with
> Rev.
> 

In the meantime, you should be able to find cheap
copies of HyperCard books in second-hand bookstores.

> JS> The best news for the documentation is that you
> can
> JS> expect some serious changes for the best very
> soon, as
> JS> Runtime Revolution has made a commitment to
> improving
> JS> the documentation dramatically for the next
> version --
> JS> so stay tuned !
> 
> I think they will have to, or they will stay a very
> niche player.
> Still, sounds as if they are at least aware of the
> issue.
> 

They are aware of the situation ; the main problem
isn't that there's not enough documentation, but that
it's too hard to find what you're looking for.

Some time ago, they started including a Documentation
search stack, which helps a lot as well ; but requires
that you have an idea of what you're looking for and
how it is called.

Moreover, the current documentation is geared towards
being a reference ; but doesn't really provide for
other learning styles -- expect big changes soon !

> I recently tried to broker the sale of a good
> software product to a
> big (and very profitable) distributor. They liked
> the product but
> turned it down, because they felt it would cost too
> much to document.
> They typically allocate a substantial % of the
> development budget for
> the technical writing. They say that far too many
> developers are more
> interested in the code than the docs, which makes
> their products
> unviable no matter how good the code is...
> 
> ------------------ 
> Geoff Caplan
> 

Well, as I make my living as a programmer, I have to
admit that documentation is less important to me than
getting the darn thing to work properly.

However, writing documentation is a bit of an art, and
it's often better to have someone else write the docs,
because this person is less likely to take for granted
what the developer knows.

If a program serves its purpose, then someone will
turn up to try and explain how it works ; or someone
else will program some alternative with a more
accessible interface and better docs.

Just the nature of the beast, I'd say.

Jan Schenkel.


	
		
__________________________________
Do you Yahoo!?
Friends.  Fun.  Try the all-new Yahoo! Messenger.
http://messenger.yahoo.com/