looks great!
Thanks and bye,
Simon
Sincerely,
Michael Cotterell
mepcot...@gmail.com
mep...@uga.edu
P.S. - Check out ScalaTion (http://code.google.com/p/scalation/), a
Domain-Specific Language for Modeling & Simulation.
Also, to begin: Concerning "Documentation of the core libs needs to be
treated at least as seriously as the code.", I believe this is vital.
When I open up the ScalaDoc for Scala itself, I shouldn't see any
methods that are undocumented. I can deal with the implementation
being undocumented, but the API documentation should be thorough.
--
Sincerely,
Michael Cotterell
mepcot...@gmail.com
mep...@uga.edu
P.S. - Check out ScalaTion (http://code.google.com/p/scalation/), a
Domain-Specific Language for Modeling & Simulation. #blatantplug
Yuvi
I'm glad things are moving forward. However, I'm pretty skeptical
things will move forward unless there is someone with the time and the
interest to *manage* contributions. Paul is the closest we have to a
manager at the moment, but he's busy and by his own admission more
interested in writing code of his own.
We need a community liaison. Someone to answer questions, merge
trivial pull requests (e.g., documentation), review other patches,
coordinate volunteers, invite participation, etc, etc.
We could have an army of volunteers (actually, I think we already do),
but with the current structure of knowledge and permissions it's
impossible for a volunteer to do anything other than get discouraged.
Yuvi
I think writing documentation is sexy, but why would I even bother if
it will never get merged in?
Yuvi
Yuvi
________________________________
This e-mail message (including any attachments) is for the sole use of
the intended recipient(s) and may contain confidential and privileged
information. If the reader of this message is not the intended
recipient, you are hereby notified that any dissemination, distribution
or copying of this message (including any attachments) is strictly
prohibited.
If you have received this message in error, please contact
the sender by reply e-mail message and destroy all copies of the
original message (including attachments).
"I don't see any reason why a core committer would even need to be
tasked for this. All we need is a couple of users who are capable of
distinguishing good/bad correct/incorrect documentation. They could
commit the changes directly."
We already have the volunteers. People are already interested. There
is just no one to manage them and make use of them.
Everyone I've talked to about contributing to Scala (including current
contributors) had to be rebuffed or ignored half a dozen times before
they got something in. For someone who "just wants to help" (i.e. is
looking for a task instead of doing one in advance) it's straight up
impossible.
Anyway, I feel my tone drifting a little toward negativity ... which
is not at all what I'm trying to convey. This problem is eminently
fixable. And from what I've heard, Typesafe is already working on it.
Just not publicly.
Yuvi
I would like to second that sentiment. I like writing documentation after I have unearthed some undocumented details. The last time I tried it, the documentation never made it into the code base. I got the impression that documentation is not valued.
> It seems self-evident that bad documentation is worse than no documentation (or at least equivalently bad). Hence someone would have to painstakingly check your documentation and in particular any examples contained therein for correctness. As it's a reasonable assumption that the lack of documentation in the first place (which, in any case, is these days is not as much of a problem as it once was) is down to the available time of the scala committers, it follows that there's a good chance they won't have time to check any documentation which is "externally" provided.
Chris,
This point of view assumes that all parts of the codebase are equally important and complex. Sure, compiler internals probably cannot be documented by many community members but there are many sharp folks who have been using Scala for a while and they can document, say, Collections library very well, and can figure out a lot of details by simply reading the source.
Those people can improve many parts of documentation a great deal, if they know their changes have good chance of being merged in after a peer review. And keep in mind that Joe The Scala programmer doesn't typically look for compiler plugins documentation, but Collections library is something very relevant to him.
--
MK
http://github.com/michaelklishin
http://twitter.com/michaelklishin
Now, I'm failing to see why we need anyone else to write Scaladoc
except for the person... who wrote the original code (or whoever
maintains it).
Crowd sourcing documentation may be fine in theory - but in practice
it may become a headache for someone who's going to colate it into
proper style/english/format.
Colladoc has incredible potential. I was totally bummed when Scalathon just did not have the budget to bring out Petr Hosek to promote the project and find no contributors.
Colladoc should continue getting attention, but we can't wait for it. In the meantime it should be a smooth and simple matter to fork scala/scala on GitHub, add your documentation and send a pull request. I did it a couple times and got stuff in. But it took a while, and if more people start doing it Paul will probably just go nuts :) Also it came after a long exchange of emails with him.
Colladoc has incredible potential. I was totally bummed when Scalathon just did not have the budget to bring out Petr Hosek to promote the project and find no contributors.
Colladoc should continue getting attention, but we can't wait for it. In the meantime it should be a smooth and simple matter to fork scala/scala on GitHub, add your documentation and send a pull request. I did it a couple times and got stuff in. But it took a while, and if more people start doing it Paul will probably just go nuts :) Also it came after a long exchange of emails with him.The problem here is that everyone except Paul still has to commit to SVN, thereforeintegrating a pull request form github requires manual work. This will be fixed once themain repository moves.
- Package Object Based Module System Allow for the definition of the public interface(s) to an entire package:
- This is an interesting improvement, but we currently do not have the resources to implement it. If someone wants to step up doing it they are more than welcome. The last two times we went through this discussion, people were pushing very hard but then nothing whatsoever happened. So we are naturally sceptical that this would be different now, but are willing to be shown otherwise.
- Treat core lib docs more seriously: Heather is doc-czarina
- Heather Miller has stepped up to be the Documentation Czar. She will oversee the quality of existing documentation, identify where it is missing, and improve it by accepting contributions and actively looking for people who are in a position to document specific areas. Additionally, we are fleshing out a reviewing policy that specifies minimal requirements for documentation, among other things.
- Appoint a community liaison person
- Agreed.
Please visit https://github.com/jrudolph/scala-android-libs
--
Johannes
-----------------------------------------------
Johannes Rudolph
http://virtual-void.net