State of Docs [was] Re: Around again, and docs lead role

[rm]

On Wed, May 07, 2003 at 11:52:46PM +0100, Neil Jerram wrote:
> >>>>> "rm" == rm  <address@hidden> writes:
> 
>     rm> I started writing up some info last night but i'm not shure
>     rm> whether the lack of documentation actually manifests some
>     rm> public vs. private API issue.
> 
> Now, no, it just manifests lack of documentation, I'm afraid :-)
> In the future, though, I do think it would be nice to reach a
> situation where
> 
>          documented <=> public and supported API

Yes. Right now, whenever i stumble upon a usefull but undocumented
part of the Guile API i'm somehow reluctant to use it since i fear
that it's not as stable as the documented part.
Who to consult in such a case? Guile-devel or Guile-user?


>     rm> Hmm, there a a handfull of pretty good Scheme intros
>     rm> available, why bother duplicating these efforts (better: write
>     rm> a Guile-specific addendum for one of these).
> 
> Tricky one, but I think if we get the rest of the GUile docs right,
> and bring more users on board, the need (or not) for this will become
> clearer.

Yes, i would assume that it's up to those who write the documentation
for guile-embedding applications to provide helpfull intros/tutorials.
After all: most general Scheme tutorials will present things like
'my-fact' or 'is-prime?' while users probably want to read about
'print-in-blue' or 'image-blur' ....

>     rm> Yes. And it would be _very_ helpfull if the documentation
>     rm> would mention what modules need to be "used" for certain
>     rm> functions [(ice-9 regexp) for regular expressions ...).
> 
> Completely agree; it's just a bug if the necessary use-module isn't
> documented.  Patches welcome!

Ok, next time i find one ...
BTW, in case i have a documentation patch: where to send it to?
Post it here?

>     rm> Another question: there's some very good information in the
>     rm> guile-workbook CVS module. But sometimes it's hard to tell
>     rm> whether a piece is documenting an existing fact of Guile or
>     rm> rather proposing a new impementation.
> 
> IMO the starting assumption should be that workbook stuff is not
> implemented and so not valid as documentation.  If you can identify
> any text that is valid, then ideally, please convert it to a patch
> against the manual.

Finally, a proposal: I think it would be rather helpfull if the
documentation for C functions as well as CPP makros would include
the type specifier. So, instead of:

 scm_make_vector (k, fill)

give

 scm_c_make_vector (unsigned long int k, SCM fill)

Not having the parameter types is sometimes missleading, esp. if
the same parameter name sometimes stands for a C value and sometimes
for a SCM value (see for ex.: 'scm_vector_set_x vector k obj',  where 'k'
stands for SCM value).
I'm willing to take over that job and update the relevant parts over
the next few weeks if people find this helpfull.

Thanks,

    Ralf