Howdy, Alvis: I bless you, as Community Manager, as our new Documentation Shepherd.
We take our docs seriously. They *are* just important as code. We don't need your resume, you got the job :) Don't be afraid to hurt our feelings. We know our docs are not very accessible. Be brutally honest about what needs to change. Duke On Mon, Oct 24, 2011 at 1:03 PM, Alvis Yardley <[email protected]> wrote: > Hello: > > I'll offer to "take on" the documentation thing. The "Constructive Whining" > document I've been working on, essentially, boils down to one thing: > Documentation, to include gathering up and setting a torch to (well ..., at > least properly archiving) all of the incorrect and so very, very misleading > documentation, floating out on the net right now. (I've spent hours and > hours and hours over these last several weeks, following down > briar-and-bramble-filled trails because of out-of-date documentation, e.g., > /parrot/docs; WikiBooks; and > http://trac.parrot.org/parrot/wiki/HLL%20Resources, to name just a few of > the examples.) > > This said, I am very "new" (by which I mean old and returning after about > almost nine years of absence from Parrot) and, consequently, may not be the > best choice to take the lead on something of this magnitude.[*] I'll leave > this for others to decide. Still, I seriously and sincerely want/need > Parrot's documentation to "make sense." Because, as of now, it is, to > parrot (pun intended) cotto, "something of a mess."[**] > > Regards, > > Alvis > > P.S. If it helps: I was the Editor-n-Chief of my law school's Law Review; > clerked (meaning I substantially wrote several of the opinions) for a former > State Supreme Court Justice; wrote and edited many, many legal briefs, legal > opinions, yada, yada; published a few law review/law related articles; and > published several op-eds in various smallish newspapers. I have also > edited, but not written, several technical manuals for, now, old legacy > systems. None of which is impressive. I mean merely to point out one > thing: I can write. > > Note: I'm happy to give anyone a run down on my technical skills as > well (if anyone is > actually interested). > > P.S.S. Duke, I am still working on the "Constructive Whining" document. > Fortunately, I discovered something this weekend which "sheds" a great deal > of light both on Parrot and on it's document set. Unfortunately, however, > this has required me to re-write, almost completely, what I had earlier > written. (I know these are rather opaque remarks, but, hopefully, they'll > make sense when I complete the re-write and send it to you.) > > --------------- > [*] This said, if someone doesn't do it, Parrot may be hard-pressed to > support the needs of its prospective HLL-developers, who, I believe, want > their projects to perform superior to, but at least competitive with, > projects developed on the JVM or the CLI. > > [**] I would like to take this opportunity to make mention of one important > point: As I am certain everyone on this list is aware, the success of > getting the documentation set in order will require (1) specific direction > "from the top," so-to-speak, and (2) a great deal of cooperation from the > "core" developers. What I'm trying to say is, in order for a documentation > project to succeed, the documenting of the project must be seen, by all, as > almost[***] as important as the code. > > And, truthfully, it is. If, for no other reason than, project > membership changes, but the project (and the reasons for its coming into > being, so-to-speak), hopefully, goes on, and new members are left with > whatever code and documentation the former members left behind. In short, > it is not just a project-maintainability-type thing, but a > project-sustainability-type thing. > > [***] Fwiw, I never have been one to subscribe to the notion that the > documentation is "just as important as the code." Why? Two reasons: (1) > The code is the deliverable and (2) in the end, you have the code. And, > although it may prove unreasonably and unnecessarily painful to do so, if > one person wrote it -- given sufficient desire and time -- another can > figure it out. It's just that, often, the latter are lacking.) > > These latter remarks are just my $0.02 and, perhaps, all they're worth. > :-) > > > On 10/24/2011 12:45 PM, Jonathan "Duke" Leto wrote: > > Howdy, > > I am at the Git Together 2011 right now, so I am time constrained. > > Documentation Shepherd: > https://twitter.com/#!/parrotvm/status/128518846997999618 > > To clarify, I have been fiddling around with Buildbot, but I don't care too > much about whether we use Jenkins of Buildbot. But we absolutely, positively > need to have distributed testing. This will solve *so many problems*. > > I talked to Alexander Graf from qemu and he showed me how I can > generate binary rpms for Parrot for many different platforms via the > build.opensuse.org build server. I will send another email with all > the gory details. > > I talked with RTEMS people and they are still very excited about getting > Parrot > on RTEMS. They are very close to getting dlfunc support in RTEMS, which is > huge, and will lay the foundation for dynamic languages on real-time > systems. > No concrete plans yet, but wheels are turning. > > +1 to setting up a community metrics website. Perhaps metrics.parrot.org ? > > Duke > > On Mon, Oct 24, 2011 at 1:20 AM, Christoph Otto <[email protected]> wrote: > > Howdy, > > This weekend, dukeleto++ and I had the privilege of attending the GSoC > Mentor Summit. The summit is a participant-run unconference for mentors > of GSoC projects, by the hackers for the hackers, at Google's offices > and on their dime. Both of duke and I picked up a treasure trove of > ideas and made some good connections with OSS hackers who we wouldn't > usually get to hang out with. I tried to take notes at all the sessions > I attended and have boiled them down to a delicious list of action > items. There's some great stuff in the list that I hope will help make > Parrot a better project and community, but it's considerably more than I > can handle all by my lonesome. Below is a summary list of the tasks I > came up with. > > * Jenkins - it's Java, but it's also awesome. We need better CI and > many projects are using Jenkins to some very cool (and very lazy) > automated testing. This would also help us make better use of the GCC > compile farm and OSUOSL's Supercell. > * pdf.js apparently has a pretty cool bot. Someone outght to see if > there's anything worth stealing and report back to parrot-dev. > * dddash.ep.io is a spiffy and simple graphical display of developer > metrics. This might be fun to put on a subdomain of parrot.org. > * docs owner - our docs have always been something of a mess. If > someone's interested, we could benefit from having a hacker who owns > our documentation and makes it his/her business to make our docs > shine. This is a substantial commitment. > * gsoc/gci analysis - We need to know how gsoc and gci are helping > Parrot, what our goals are and if we're meeting them. We need > someone to lead this effort and to do some reporting about how gsoc > has gone in the past and where we can improve. Note that Google > likes orgs that do this because it shows that we're concerned about > long-term results. > > I'll be going through them in more detail at #parrotsketch this Tuesday. > If anything on the list looks interesting to any of you, please drop by > and we'll see about putting you to work. Alternately, just jump right > in! It's almost always better to ask for forgiveness than permission > when hacking on Parrot.* dukeleto++ has already started seriously > looking at Jenkins and I've got a couple of blog posts to write and toys > to experiment with. > > All this may be more than we can handle during one #ps, but I hope we > can find people to work on a couple of these items. Be thinking about > what you'd like to do and I'll see you at #ps, > > Christoph > > > > *Except where it's not. > _______________________________________________ > http://lists.parrot.org/mailman/listinfo/parrot-dev > > > > > > _______________________________________________ > http://lists.parrot.org/mailman/listinfo/parrot-dev > > -- Jonathan "Duke" Leto <[email protected]> Leto Labs LLC 209.691.DUKE // http://labs.leto.net NOTE: Personal email is only checked twice a day at 10am/2pm PST, please call/text for time-sensitive matters. _______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
