Working on Scala documentation

> I've been seeing a lot of talk about scala's documentation being
> insufficient. And I have to say I agree. Especially in the scaladoc of the
> standard library (my main resource).

i think the docs don't explain aliases e.g. using () is really using
apply. imho that is a hindrance for new users.

sincerely.

On Fri, Mar 13, 2009 at 1:43 PM, Arthur Peters <amp@singingwizard.org> wrote:

I've been seeing a lot of talk about scala's documentation being insufficient. And I have to say I agree. Especially in the scaladoc of the standard library (my main resource).

I'm considering trying my hand at adding docs my self. So I'd like to ask a couple of questions:

I don't know scala all that well (though I'm learning fast and I'm sure writing documentation would teach me well). So in some ways I'm not qualified to write documentation, however if I could submit the patches to someone who was qualified for review I'd feel comfortable with it. Would this be useful? or would the review be just as much work as writing the docs from scratch?

I'm in a similar boat -- I like documentation, and don't at all mind helping write it, but I'm still too much of a newbie here to feel entirely comfortable.

So here's a suggestion: this might well make a good group project.  We might consider a new list, scala-doc (assuming that doesn't already exist), with a specific mandate to work together on the documentation.  Suggested docs would be posted to the group for review and commentary before being checked in.  That might work on both the scaladoc in the sources, and on meta-documentation in the wikis.  That way, those of us who are clueful but slightly ignorant could help out, while still being reviewed by folks who understand the lay of the land better.

Opinions?  Would people be interested in working together like this?  We'd need a mix of enthusiasts who would work on it, and experienced hands willing to read stuff and sanity-check it...

We'd be very happy to accept patches for good documentation. It's a
non-trvial job, from which many people can benefit.

Cheers

(Accidentally sent this only to Justin)

About a year ago a similar effort was started complete with a new
repository and people needing to sign an agreement that would release
their documentation efforts to EPFL. I signed up for a bit myself,
did some work on it, then got busy doing other stuff. I believe that
the web site and the wiki pages dedicated to it are still there and
could probably just be started up again.

Adding a mailing list to the mix *might* help. Just getting people to
sign up and do an unglamorous difficult job is the bigger issue. Good
technical writing is not trivial.

On Fri, Mar 13, 2009 at 1:55 PM, Justin du coeur wrote:
> On Fri, Mar 13, 2009 at 1:43 PM, Arthur Peters
> wrote:
>>
>> I've been seeing a lot of talk about scala's documentation being
>> insufficient. And I have to say I agree. Especially in the scaladoc of the
>> standard library (my main resource).
>>
>> I'm considering trying my hand at adding docs my self. So I'd like to ask
>> a couple of questions:
>>
>> I don't know scala all that well (though I'm learning fast and I'm sure
>> writing documentation would teach me well). So in some ways I'm not
>> qualified to write documentation, however if I could submit the patches to
>> someone who was qualified for review I'd feel comfortable with it. Would
>> this be useful? or would the review be just as much work as writing the docs
>> from scratch?
>
> I'm in a similar boat -- I like documentation, and don't at all mind helping
> write it, but I'm still too much of a newbie here to feel entirely
> comfortable.
>
> So here's a suggestion: this might well make a good group project.  We might
> consider a new list, scala-doc (assuming that doesn't already exist), with a
> specific mandate to work together on the documentation.  Suggested docs
> would be posted to the group for review and commentary before being checked
> in.  That might work on both the scaladoc in the sources, and on
> meta-documentation in the wikis.  That way, those of us who are clueful but
> slightly ignorant could help out, while still being reviewed by folks who
> understand the lay of the land better.
>
> Opinions?  Would people be interested in working together like this?  We'd
> need a mix of enthusiasts who would work on it, and experienced hands
> willing to read stuff and sanity-check it...
>

On Fri, Mar 13, 2009 at 2:05 PM, Jim Miller <gordon.j.miller@gmail.com> wrote:

Adding a mailing list to the mix *might* help.  Just getting people to
sign up and do an unglamorous difficult job is the bigger issue.  Good
technical writing is not trivial.

Yep, absolutely -- I've done a fair amount of it, and still consider myself only adequate.  But if we could get a community going, of people helping each other get better and supporting each others' efforts, it at least improves the odds of making some progress...

Could you post a link to this older project? I looked around and I can't find it.

Also as far as technical writing goes: I was think mainly of the 3 or 4 sentence descriptions of API functions. And although they are not trivial to write they are nice bite sized pieces.

And as for glamor, maybe we could add a @documenationauthor tag to scaladocs. I for one am very proud to get my name in a major projects code base.

So we should offer small manageable pieces and if you document an entire object or class you get undying fame. ;-)

-Arthur


On Fri, Mar 13, 2009 at 2:05 PM, Jim Miller <gordon.j.miller@gmail.com> wrote:

(Accidentally sent this only to Justin)

About a year ago a similar effort was started complete with a new
repository and people needing to sign an agreement that would release
their documentation efforts to EPFL.  I signed up for a bit myself,
did some work on it, then got busy doing other stuff.  I believe that
the web site and the wiki pages dedicated to it are still there and
could probably just be started up again.

Adding a mailing list to the mix *might* help.  Just getting people to
sign up and do an unglamorous difficult job is the bigger issue.  Good
technical writing is not trivial.

On Fri, Mar 13, 2009 at 1:55 PM, Justin du coeur <jducoeur@gmail.com> wrote:
> On Fri, Mar 13, 2009 at 1:43 PM, Arthur Peters <amp@singingwizard.org>
> wrote:
>>
>> I've been seeing a lot of talk about scala's documentation being
>> insufficient. And I have to say I agree. Especially in the scaladoc of the
>> standard library (my main resource).
>>
>> I'm considering trying my hand at adding docs my self. So I'd like to ask
>> a couple of questions:
>>
>> I don't know scala all that well (though I'm learning fast and I'm sure
>> writing documentation would teach me well). So in some ways I'm not
>> qualified to write documentation, however if I could submit the patches to
>> someone who was qualified for review I'd feel comfortable with it. Would
>> this be useful? or would the review be just as much work as writing the docs
>> from scratch?
>
> I'm in a similar boat -- I like documentation, and don't at all mind helping
> write it, but I'm still too much of a newbie here to feel entirely
> comfortable.
>
> So here's a suggestion: this might well make a good group project.  We might
> consider a new list, scala-doc (assuming that doesn't already exist), with a
> specific mandate to work together on the documentation.  Suggested docs
> would be posted to the group for review and commentary before being checked
> in.  That might work on both the scaladoc in the sources, and on
> meta-documentation in the wikis.  That way, those of us who are clueful but
> slightly ignorant could help out, while still being reviewed by folks who
> understand the lay of the land better.
>
> Opinions?  Would people be interested in working together like this?  We'd
> need a mix of enthusiasts who would work on it, and experienced hands
> willing to read stuff and sanity-check it...
>

O/H Justin du coeur έγραψε:
> On Fri, Mar 13, 2009 at 1:43 PM, Arthur Peters > wrote:
>
> I've been seeing a lot of talk about scala's documentation being
> insufficient. And I have to say I agree. Especially in the
> scaladoc of the standard library (my main resource).
>
> I'm considering trying my hand at adding docs my self. So I'd like
> to ask a couple of questions:
>
> I don't know scala all that well (though I'm learning fast and I'm
> sure writing documentation would teach me well). So in some ways
> I'm not qualified to write documentation, however if I could
> submit the patches to someone who was qualified for review I'd
> feel comfortable with it. Would this be useful? or would the
> review be just as much work as writing the docs from scratch?
>
>
> I'm in a similar boat -- I like documentation, and don't at all mind
> helping write it, but I'm still too much of a newbie here to feel
> entirely comfortable.
>
> So here's a suggestion: this might well make a good group project.� We
> might consider a new list, scala-doc (assuming that doesn't already
> exist), with a specific mandate to work together on the
> documentation.� Suggested docs would be posted to the group for review
> and commentary before being checked in.� That might work on both the
> scaladoc in the sources, and on meta-documentation in the wikis.� That
> way, those of us who are clueful but slightly ignorant could help out,
> while still being reviewed by folks who understand the lay of the land
> better.
>
> Opinions?� Would people be interested in working together like this?�
> We'd need a mix of enthusiasts who would work on it, and experienced
> hands willing to read stuff and sanity-check it...
(I just want to add a related suggestion, not comment to your particular
message)

I think the "Use" feature of javadocs is sorely missed in scaladocs.
(The page accessible in javadocs' top header along with "Overview",
"Package", "Class", "Tree", "Deprecated", "Index", "Help").
It's extremely handy for exploring and navigating apis, though probably
quite difficult to implement (is there any mirror-like api around for
scala?)

Dimitris

> Date: Fri, 13 Mar 2009 14:23:42 -0400
> From: Arthur Peters
> CC: Scala list
>
> --0016363b7c705e615304650433c6
> Content-Type: text/plain; charset="UTF-8"
> Content-Transfer-Encoding: 7bit
>
> Could you post a link to this older project? I looked around and I can't
> find it.

I think Jim is referring to the "Documentation effort" the Scala wiki at

http://scala.sygneca.com/docs/start

but given that page's history, the idea did not take off.

One drawback was that it required using hg to download a 270mg distribution,
which was a mirror, so there are questions of forked code, merging, etc.

> Also as far as technical writing goes: I was think mainly of the 3 or 4
> sentence descriptions of API functions. And although they are not trivial to
> write they are nice bite sized pieces.
>
> And as for glamor, maybe we could add a @documenationauthor tag to
> scaladocs. I for one am very proud to get my name in a major projects code
> base.
>
> So we should offer small manageable pieces and if you document an entire
> object or class you get undying fame. ;-)
>
> -Arthur

Yes, that was the one I was referring to, and yes it was painful to get started.

On Fri, Mar 13, 2009 at 3:08 PM, David J. Biesack wrote:
>> Date: Fri, 13 Mar 2009 14:23:42 -0400
>> From: Arthur Peters
>> CC: Scala list
>>
>> --0016363b7c705e615304650433c6
>> Content-Type: text/plain; charset="UTF-8"
>> Content-Transfer-Encoding: 7bit
>>
>> Could you post a link to this older project? I looked around and I can't
>> find it.
>
> I think Jim is referring to the "Documentation effort" the Scala wiki at
>
>  http://scala.sygneca.com/docs/start
>
> but given that page's history, the idea did not take off.
>
> One drawback was that it required using hg to download a 270mg distribution,
> which was a mirror, so there are questions of forked code, merging, etc.
>
>> Also as far as technical writing goes: I was think mainly of the 3 or 4
>> sentence descriptions of API functions. And although they are not trivial to
>> write they are nice bite sized pieces.
>>
>> And as for glamor, maybe we could add a @documenationauthor tag to
>> scaladocs. I for one am very proud to get my name in a major projects code
>> base.
>>
>> So we should offer small manageable pieces and if you document an entire
>> object or class you get undying fame. ;-)
>>
>> -Arthur
>
> --
> David J. Biesack, SAS
> SAS Campus Dr. Cary, NC 27513
> www.sas.com    (919) 531-7771
>

I think if people are just writing docs it would be best to just checkout the Scala svn.   If people want local source control, I have a more compact Mercurial repo on bitbucket and Paul Phillips has a Git repo on Github (although I'm not sure as to the compactness).

On Fri, Mar 13, 2009 at 3:08 PM, David J. Biesack <David.Biesack@sas.com> wrote:

> Date: Fri, 13 Mar 2009 14:23:42 -0400
> From: Arthur Peters <arthur.peters@gmail.com>
> CC: Scala list <scala@listes.epfl.ch>
>
> --0016363b7c705e615304650433c6
> Content-Type: text/plain; charset="UTF-8"
> Content-Transfer-Encoding: 7bit
>
> Could you post a link to this older project? I looked around and I can't
> find it.

I think Jim is referring to the "Documentation effort" the Scala wiki at

 http://scala.sygneca.com/docs/start

but given that page's history, the idea did not take off.

One drawback was that it required using hg to download a 270mg distribution,
which was a mirror, so there are questions of forked code, merging, etc.

> Also as far as technical writing goes: I was think mainly of the 3 or 4
> sentence descriptions of API functions. And although they are not trivial to
> write they are nice bite sized pieces.
>
> And as for glamor, maybe we could add a @documenationauthor tag to
> scaladocs. I for one am very proud to get my name in a major projects code
> base.
>
> So we should offer small manageable pieces and if you document an entire
> object or class you get undying fame. ;-)
>
> -Arthur

--
David J. Biesack, SAS
SAS Campus Dr. Cary, NC 27513
www.sas.com    (919) 531-7771

--
http://erikengbrecht.blogspot.com/

Would it be possible to write executable documentation and publish that in
the Scaladocs in some way? Would it be useful?

The Ruby folks created executable specs describing the behavior of the Ruby
language. I've glanced at it, but I don't know how applicable it would be
for this kind of project:

http://rubyspec.org/

Reading a bulleted list of Spec-generated documentation would likely not be
as useful as the prose that appears in the core JavaDocs. It would have the
advantage of being executable and therefore more likely to be maintained.
Of course, if you were using Specs, you can always write incorrect specs --
saying it should "throw an IllegalArgumentException if passed a null" but
the test would verify nulls were accepted silently.

This is more of a "what if?" question - I'm not saying that using Specs or
ScalaTest matchers is the correct solution - just wondering if there's an
opportunity for something new, or modifying something that already exists.

Dan

Arthur Peters-2 wrote:
>
> Hello,
>
> I've been seeing a lot of talk about scala's documentation being
> insufficient. And I have to say I agree. Especially in the scaladoc of the
> standard library (my main resource).
>
> I'm considering trying my hand at adding docs my self. So I'd like to ask
> a
> couple of questions:
>
> I don't know scala all that well (though I'm learning fast and I'm sure
> writing documentation would teach me well). So in some ways I'm not
> qualified to write documentation, however if I could submit the patches to
> someone who was qualified for review I'd feel comfortable with it. Would
> this be useful? or would the review be just as much work as writing the
> docs
> from scratch?
>
> Who could I send patches to and is there anything special I need to do
> about
> the patches? Do I need to sign a copy write assignment?
>
> I hope I can help out.
> -Arthur
>
>

The problem is that the two types of documentation (those in the code)
and those in the javadoc communicate to two different audiences.
True, good programming languages make the intent of the code more
obvious, but ultimately they are communicating two different things.
The program is communicating to the machine what steps to perform
while the javadoc communicates to the human how use the
class/function.

I'm not sure that using Spec generated documentation does anything to
answer the questions that good documentation answers, why and under
what conditions does the class/function work and why would you use it.

On Sat, Mar 14, 2009 at 10:59 AM, Daniel Wellman wrote:
>
> Would it be possible to write executable documentation and publish that in
> the Scaladocs in some way?  Would it be useful?
>
> The Ruby folks created executable specs describing the behavior of the Ruby
> language.  I've glanced at it, but I don't know how applicable it would be
> for this kind of project:
>
> http://rubyspec.org/
>
> Reading a bulleted list of Spec-generated documentation would likely not be
> as useful as the prose that appears in the core JavaDocs.  It would have the
> advantage of being executable and therefore more likely to be maintained.
> Of course, if you were using Specs, you can always write incorrect specs --
> saying it should "throw an IllegalArgumentException if passed a null" but
> the test would verify nulls were accepted silently.
>
> This is more of a "what if?" question - I'm not saying that using Specs or
> ScalaTest matchers is the correct solution - just wondering if there's an
> opportunity for something new, or modifying something that already exists.
>
> Dan
>
>
>
> Arthur Peters-2 wrote:
>>
>> Hello,
>>
>> I've been seeing a lot of talk about scala's documentation being
>> insufficient. And I have to say I agree. Especially in the scaladoc of the
>> standard library (my main resource).
>>
>> I'm considering trying my hand at adding docs my self. So I'd like to ask
>> a
>> couple of questions:
>>
>> I don't know scala all that well (though I'm learning fast and I'm sure
>> writing documentation would teach me well). So in some ways I'm not
>> qualified to write documentation, however if I could submit the patches to
>> someone who was qualified for review I'd feel comfortable with it. Would
>> this be useful? or would the review be just as much work as writing the
>> docs
>> from scratch?
>>
>> Who could I send patches to and is there anything special I need to do
>> about
>> the patches? Do I need to sign a copy write assignment?
>>
>> I hope I can help out.
>> -Arthur
>>
>>
>
> --
> View this message in context: http://www.nabble.com/-scala--Working-on-Scala-documentation-tp22501718p...
> Sent from the Scala mailing list archive at Nabble.com.
>
>