GSOC: Collaborative Scaladoc

Hello to everyone in the Scala community,

As a student who has been selected to Google Summer of Code in order to
work on Scala programming language project, I would like to introduce
myself and especially my project to the Scala community.

My name is Petr Hosek. I am a student, teaching assistant and most of
all programmer currently living in Prague. At the moment, I am studying
at Charles University in Prague, Faculty of Mathematics and Physics as a
second year graduate student finishing this year. My primary field of
study are software systems, my specialization is component, distributed
and dependable systems as well as formal verification methods. I am
highly interested in software engineering, model-driven development and
programming, especially using new programming languages.

I discovered Scala two years ago as an ultimate research project
combining knowledge of object-oriented and functional programming with
knowledge of component systems and other interesting concepts and since
that, I am very keen on this language and I have become unofficial Scala
evangelist propagating this language among other students as well as
among teachers and professors at the university. Due to my interest in
Scala programming language and Scala development, I have also applied
for doctoral school at Ecole Polytechnique Federale de Lausanne in order
to become a member of research team around Professor Martin Odersky to
be able to participate actively in Scala development.

Therefore, when I have found out that Scala project will be
participating in Google Summer of Code 2010, an opportunity to become an
active Scala developer highly interested me and I have immediately
decided to enroll with my proposal. Even though there were many
interesting topics and I have been originally considering nearly all of
them, one really stood out as it is addressing one of the major flaws of
Scala project. During my experience with Scala, I have found out that
the quality of documentation is one of the biggest drawbacks. This is
even more frustrating as this is the part of platform that many new as
well as experienced Scala programmers heavily rely on. Therefore, I have
become really interested in the idea of Collaborative Scaladoc which
aims to address this issue.

Goal of this project is to explore the possibility of using social
collaboration for development of Scala project documentation. This may
be interesting as there are many developers using Scala that would like
to collaborate on Scala platform in order to make it better, but does
not have enough knowledge or enthusiasm to directly contribute to the
development of Scala compiler and related tools. The Collaborative
Scaladoc tool will allow them to contribute by improving the Scala
documentation. Moreover, Collaborative Scaladoc will also allow other
people such as language correctors to contribute as well in
user-friendly and accessible way.

Even though the Collaborative Scaladoc was originally meant to be used
for the Scala project itself, I believe it would be useful for other
projects such as Lift Framework as well. Therefore, I would like to make
it available as a generally usable tool provided as a part of Scala
project. This may be other major advantage for Scala as I am not aware
of any other similar project even though it would be generally needed
for other platforms as well.

The project mentor is Gilles Dubochet. Progress as well as details about
the Collaborative Scaladoc development will be regularly published at my
website http://www.petrhosek.name/. Project itself will be hosted at
http://code.google.com/p/collaborative-scaladoc/.

Best Regards,

Petr Hosek

2010/5/15 Petr Hosek <mail@petrhosek.name>

Hello to everyone in the Scala community,

As a student who has been selected to Google Summer of Code in order to
work on Scala programming language project, I would like to introduce
myself and especially my project to the Scala community.

Hi Petr,

Thanks for sharing all this interesting information.

Happy coding during the summer!

On Sat, May 15, 2010 at 12:42 PM, Petr Hosek <mail@petrhosek.name> wrote:

Hello to everyone in the Scala community,

As a student who has been selected to Google Summer of Code in order to
work on Scala programming language project, I would like to introduce
myself and especially my project to the Scala community.

My name is Petr Hosek. I am a student, teaching assistant and most of
all programmer currently living in Prague. At the moment, I am studying
at Charles University in Prague, Faculty of Mathematics and Physics as a
second year graduate student finishing this year. My primary field of
study are software systems, my specialization is component, distributed
and dependable systems as well as formal verification methods. I am
highly interested in software engineering, model-driven development and
programming, especially using new programming languages.

I discovered Scala two years ago as an ultimate research project
combining knowledge of object-oriented and functional programming with
knowledge of component systems and other interesting concepts and since
that, I am very keen on this language and I have become unofficial Scala
evangelist propagating this language among other students as well as
among teachers and professors at the university. Due to my interest in
Scala programming language and Scala development, I have also applied
for doctoral school at Ecole Polytechnique Federale de Lausanne in order
to become a member of research team around Professor Martin Odersky to
be able to participate actively in Scala development.

Therefore, when I have found out that Scala project will be
participating in Google Summer of Code 2010, an opportunity to become an
active Scala developer highly interested me and I have immediately
decided to enroll with my proposal. Even though there were many
interesting topics and I have been originally considering nearly all of
them, one really stood out as it is addressing one of the major flaws of
Scala project. During my experience with Scala, I have found out that
the quality of documentation is one of the biggest drawbacks. This is
even more frustrating as this is the part of platform that many new as
well as experienced Scala programmers heavily rely on. Therefore, I have
become really interested in the idea of Collaborative Scaladoc which
aims to address this issue.

Goal of this project is to explore the possibility of using social
collaboration for development of Scala project documentation. This may
be interesting as there are many developers using Scala that would like
to collaborate on Scala platform in order to make it better, but does
not have enough knowledge or enthusiasm to directly contribute to the
development of Scala compiler and related tools. The Collaborative
Scaladoc tool will allow them to contribute by improving the Scala
documentation. Moreover, Collaborative Scaladoc will also allow other
people such as language correctors to contribute as well in
user-friendly and accessible way.

Even though the Collaborative Scaladoc was originally meant to be used
for the Scala project itself, I believe it would be useful for other
projects such as Lift Framework as well. Therefore, I would like to make
it available as a generally usable tool provided as a part of Scala
project. This may be other major advantage for Scala as I am not aware
of any other similar project even though it would be generally needed
for other platforms as well.

Petr,
Your project sounds very interesting... from a Scala user standpoint, from a Lift manager standpoint, and from the standpoint of someone who continues to marvel at ways technology allows people to work together.  So, a hearty "boo yah!" to you for undertaking the project.
A couple of things I would be interested in as a consumer of collaborative documentation, a couple of things I would be interest in seeing in your system:

• For APIs that were not yet frozen, I'd love to see discussion as a well as documentation, so that as the APIs are refined, people can drill down from the final documentation to understand how the APIs evolved that way.
• My primary tool for interacting with others is email.  A healthy integration between your system and email would be great (see how Posterous does this very effectively).
• A total separation between the intermediate output of your system and the actual source code would be ideal.  Rather than keeping comments around in the source and having your system over-write the source, it'd be great to have the ScalaDoc tool reach into the output of your system (do you have a name for it yet?) and grab the appropriate docs would be great.  That way there's one less change set that we have to worry about in Git.

Anyway, I'm very excited to see what you come up with.  If you need any help or anything else, please feel encouraged to ping me privately.  I'm here to support your effort!
Thanks,
David
 

The project mentor is Gilles Dubochet. Progress as well as details about
the Collaborative Scaladoc development will be regularly published at my
website http://www.petrhosek.name/. Project itself will be hosted at
http://code.google.com/p/collaborative-scaladoc/.

Best Regards,

Petr Hosek

--
Lift, the simply functional web framework http://liftweb.net
Beginning Scala http://www.apress.com/book/view/1430219890
Follow me: http://twitter.com/dpp
Surf the harmonics

Hello David,

On Sun, 2010-05-16 at 06:40 -0700, David Pollak wrote:
> Petr,
>
>
> Your project sounds very interesting... from a Scala user standpoint,
> from a Lift manager standpoint, and from the standpoint of someone who
> continues to marvel at ways technology allows people to work
> together. So, a hearty "boo yah!" to you for undertaking the project.

Thank you very much for your interest, I have to say it is really
motivating to get such feedback from you.

I plan to provide design and project plan very soon and discuss it with
the community because it is really important for me to get the feedback.

> A couple of things I would be interested in as a consumer of
> collaborative documentation, a couple of things I would be interest in
> seeing in your system:
> * For APIs that were not yet frozen, I'd love to see discussion
> as a well as documentation, so that as the APIs are refined,
> people can drill down from the final documentation to
> understand how the APIs evolved that way.

The APIs will be definitely further discussed before their
implementation and I hope to receive number of suggestions and remarks.

> * My primary tool for interacting with others is email. A
> healthy integration between your system and email would be
> great (see how Posterous does this very effectively).

The email integration sounds interesting and I will definitely consider
this idea as I have not been thinking about this before.

> * A total separation between the intermediate output of your
> system and the actual source code would be ideal. Rather than
> keeping comments around in the source and having your system
> over-write the source, it'd be great to have the ScalaDoc tool
> reach into the output of your system (do you have a name for
> it yet?) and grab the appropriate docs would be great. That
> way there's one less change set that we have to worry about in
> Git.

Right now, I plan to utilize the existing scaladoc-merge tool to allow
to include the changes, which will be held in the system, directly into
the source code. However, it should be possible to allow generating
documentation directly from the system.

> Anyway, I'm very excited to see what you come up with. If you need
> any help or anything else, please feel encouraged to ping me
> privately. I'm here to support your effort!
>
>
> Thanks,
>
>
> David

Your ideas are great and I will definitely consider them during design
and implementation of the tool.

Thank you once again for your support!

Cheers,

Petr

Hi Petr,

I've been contributing tiny bits to Scaladoc2 from time to time. One
thing I'd love to see was a way to provide usage examples, real usage
examples, so it's beyond the current @usecase, maybe a step further.
Possibly this is a bit away from the current intentions for you GoSC
project but for sure it shares lots of similarities. If you have any
interesting private message me so we can have discuss.

Cheers,
PF

On Mon, May 17, 2010 at 12:01 AM, Petr Hosek wrote:
> Hello David,
>
> On Sun, 2010-05-16 at 06:40 -0700, David Pollak wrote:
>> Petr,
>>
>>
>> Your project sounds very interesting... from a Scala user standpoint,
>> from a Lift manager standpoint, and from the standpoint of someone who
>> continues to marvel at ways technology allows people to work
>> together.  So, a hearty "boo yah!" to you for undertaking the project.
>
> Thank you very much for your interest, I have to say it is really
> motivating to get such feedback from you.
>
> I plan to provide design and project plan very soon and discuss it with
> the community because it is really important for me to get the feedback.
>
>> A couple of things I would be interested in as a consumer of
>> collaborative documentation, a couple of things I would be interest in
>> seeing in your system:
>>       * For APIs that were not yet frozen, I'd love to see discussion
>>         as a well as documentation, so that as the APIs are refined,
>>         people can drill down from the final documentation to
>>         understand how the APIs evolved that way.
>
> The APIs will be definitely further discussed before their
> implementation and I hope to receive number of suggestions and remarks.
>
>>       * My primary tool for interacting with others is email.  A
>>         healthy integration between your system and email would be
>>         great (see how Posterous does this very effectively).
>
> The email integration sounds interesting and I will definitely consider
> this idea as I have not been thinking about this before.
>
>>       * A total separation between the intermediate output of your
>>         system and the actual source code would be ideal.  Rather than
>>         keeping comments around in the source and having your system
>>         over-write the source, it'd be great to have the ScalaDoc tool
>>         reach into the output of your system (do you have a name for
>>         it yet?) and grab the appropriate docs would be great.  That
>>         way there's one less change set that we have to worry about in
>>         Git.
>
> Right now, I plan to utilize the existing scaladoc-merge tool to allow
> to include the changes, which will be held in the system, directly into
> the source code. However, it should be possible to allow generating
> documentation directly from the system.
>
>> Anyway, I'm very excited to see what you come up with.  If you need
>> any help or anything else, please feel encouraged to ping me
>> privately.  I'm here to support your effort!
>>
>>
>> Thanks,
>>
>>
>> David
>
> Your ideas are great and I will definitely consider them during design
> and implementation of the tool.
>
> Thank you once again for your support!
>
> Cheers,
>
> Petr
>
>

On Sun, May 16, 2010 at 8:01 PM, Petr Hosek <mail@petrhosek.name> wrote:

Hello David,

On Sun, 2010-05-16 at 06:40 -0700, David Pollak wrote:
> Petr,
>
>
> Your project sounds very interesting... from a Scala user standpoint,
> from a Lift manager standpoint, and from the standpoint of someone who
> continues to marvel at ways technology allows people to work
> together.  So, a hearty "boo yah!" to you for undertaking the project.

Thank you very much for your interest, I have to say it is really
motivating to get such feedback from you.

I plan to provide design and project plan very soon and discuss it with
the community because it is really important for me to get the feedback.

> A couple of things I would be interested in as a consumer of
> collaborative documentation, a couple of things I would be interest in
> seeing in your system:
>       * For APIs that were not yet frozen, I'd love to see discussion
>         as a well as documentation, so that as the APIs are refined,
>         people can drill down from the final documentation to
>         understand how the APIs evolved that way.

The APIs will be definitely further discussed before their
implementation and I hope to receive number of suggestions and remarks.

Petr,

I was thinking about something different.  I was thinking that the documentation effort for non-frozen APIs (e.g., we introduce a new API into Lift, start documenting it) includes comment and discussion.  This kind of tool would, in my opinion, allow focused community feedback/input into the APIs as well as a history of how the API evolved the way it did.

Thanks,

David
 

>       * My primary tool for interacting with others is email.  A
>         healthy integration between your system and email would be
>         great (see how Posterous does this very effectively).

The email integration sounds interesting and I will definitely consider
this idea as I have not been thinking about this before.

>       * A total separation between the intermediate output of your
>         system and the actual source code would be ideal.  Rather than
>         keeping comments around in the source and having your system
>         over-write the source, it'd be great to have the ScalaDoc tool
>         reach into the output of your system (do you have a name for
>         it yet?) and grab the appropriate docs would be great.  That
>         way there's one less change set that we have to worry about in
>         Git.

Right now, I plan to utilize the existing scaladoc-merge tool to allow
to include the changes, which will be held in the system, directly into
the source code. However, it should be possible to allow generating
documentation directly from the system.

> Anyway, I'm very excited to see what you come up with.  If you need
> any help or anything else, please feel encouraged to ping me
> privately.  I'm here to support your effort!
>
>
> Thanks,
>
>
> David

Your ideas are great and I will definitely consider them during design
and implementation of the tool.

Thank you once again for your support!

Cheers,

Petr

--
Lift, the simply functional web framework http://liftweb.net
Beginning Scala http://www.apress.com/book/view/1430219890
Follow me: http://twitter.com/dpp
Surf the harmonics

Hello David,

Thank you for your mail. I have not think about this before, but it
actually sounds really promising and I will definitely add this idea to
the list of possible features.

Thank you once again.

Regards,

Petr

On Mon, 2010-05-17 at 11:29 -0700, David Pollak wrote:
> Petr,
>
> I was thinking about something different. I was thinking that the
> documentation effort for non-frozen APIs (e.g., we introduce a new API
> into Lift, start documenting it) includes comment and discussion.
> This kind of tool would, in my opinion, allow focused community
> feedback/input into the APIs as well as a history of how the API
> evolved the way it did.
>
> Thanks,
>
> David

Hello to everyone,

I'll be working on Collaborative Scaladoc for Google Summer of Code
this summer. Colladoc is web application allowing to edit Scala
symbols documentation.

Peth Hosek and I'll be posting progress updates in official blog:
http://collaborative-scaladoc.posterous.com/

Project is hosted here: https://github.com/collaborative-scaladoc/colladoc

Same as before, you can try the application online for the Scala
standard library: http://scala-webapps.epfl.ch/colladoc/

My mentor, Vlad Ureche, project leader, Petr Hosek, and I have
developed a list of goals for the summer:
-Advanced user management and user roles.
-Comments management.
-Convenient UI for administrator.
-2-page model that Wikipedia uses, in which for every content page
there is also a "Talk" page where people can say roughly what they
think should be changed about the content page, without actually
knowing precisely how to change it.
-Better Mergedoc integration.
-Examples and help pages.

The primary goal is to make Colladoc really handy tool for editing comments.

Feedback is very welcome!

Sergey Ignatov

+1 for the talk page! Now that you have mentioned it, I do miss it.

On Fri, May 20, 2011 at 07:32, Sergey Ignatov wrote:
> Hello to everyone,
>
> I'll be working on Collaborative Scaladoc for Google Summer of Code
> this summer. Colladoc is web application allowing to edit Scala
> symbols documentation.
>
> Peth Hosek and I'll be posting progress updates in official blog:
> http://collaborative-scaladoc.posterous.com/
>
> Project is hosted here: https://github.com/collaborative-scaladoc/colladoc
>
> Same as before, you can try the application online for the Scala
> standard library: http://scala-webapps.epfl.ch/colladoc/
>
> My mentor, Vlad Ureche, project leader, Petr Hosek, and I have
> developed a list of goals for the summer:
> -Advanced user management and user roles.
> -Comments management.
> -Convenient UI for administrator.
> -2-page model that Wikipedia uses, in which for every content page
> there is also a "Talk" page where people can say roughly what they
> think should be changed about the content page, without actually
> knowing precisely how to change it.
> -Better Mergedoc integration.
> -Examples and help pages.
>
> The primary goal is to make Colladoc really handy tool for editing comments.
>
> Feedback is very welcome!
>
> Sergey Ignatov
>

Very nice.

I always appreciate the Comments sections found in the docs for
software like Postgres
so this seems like a good idea to me.

On 20 May 2011 14:46, Daniel Sobral wrote:
> +1 for the talk page! Now that you have mentioned it, I do miss it.
>
> On Fri, May 20, 2011 at 07:32, Sergey Ignatov wrote:
>> Hello to everyone,
>>
>> I'll be working on Collaborative Scaladoc for Google Summer of Code
>> this summer. Colladoc is web application allowing to edit Scala
>> symbols documentation.
>>
>> Peth Hosek and I'll be posting progress updates in official blog:
>> http://collaborative-scaladoc.posterous.com/
>>
>> Project is hosted here: https://github.com/collaborative-scaladoc/colladoc
>>
>> Same as before, you can try the application online for the Scala
>> standard library: http://scala-webapps.epfl.ch/colladoc/
>>
>> My mentor, Vlad Ureche, project leader, Petr Hosek, and I have
>> developed a list of goals for the summer:
>> -Advanced user management and user roles.
>> -Comments management.
>> -Convenient UI for administrator.
>> -2-page model that Wikipedia uses, in which for every content page
>> there is also a "Talk" page where people can say roughly what they
>> think should be changed about the content page, without actually
>> knowing precisely how to change it.
>> -Better Mergedoc integration.
>> -Examples and help pages.
>>
>> The primary goal is to make Colladoc really handy tool for editing comments.
>>
>> Feedback is very welcome!
>>
>> Sergey Ignatov
>>
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

Hi,

great to hear!

Is the focus more on the editing part or on how to merge (maybe
automated/with a single click) the changes from colladoc into the Scala
source?

Thanks and bye!

Simon

Thank you very much for your responses

On 21 May 2011 00:41, Simon Ochsenreither wrote:
> Is the focus more on the editing part or on how to merge (maybe
> automated/with a single click) the changes from colladoc into the Scala
> source?
In the opinion my mentor, autocommit is crucial in the success of the
GSoC project. ;)

At this moment have command line tool for manual merge and Colladoc
REST API for it.

There are some variants for Mergedoc integration:
1. REST API with command line tool (done)
2. Creating a git patches and manual merging
3. Server side code modification and manual git publishing
4. Server side autocommit

It would be nice to hear your comments about the options for integration.
Maybe you can propose better ways

Sergey Ignatov