proposal on website maintenance #11

Merged
merged 2 commits into from Nov 30, 2016

Projects

None yet
@SethTisue
Collaborator
SethTisue commented Oct 31, 2016 edited

"We propose that the Scala Center assume responsibility for updating and maintaining the scala-lang.org, docs.scala-lang.org, and scala.epfl.ch websites..."

hopefully 009 is the right number?

@Ichoran
Ichoran commented Oct 31, 2016

I think this is a very good idea. But it would still not quite be clear beyond "Scala Center" who is ultimately responsible for all decisions. If more than one person wants to do the work, great; if most of the work can be done by interested community members, even better! However, I would modify the proposal that not only that Scala Center assume responsibility but that one individual at Scala Center assume responsibility. It is easy to talk to a person. It is hard to talk to a center.

@heathermiller
Collaborator
heathermiller commented Oct 31, 2016 edited

It seems clear to me that the proposal proposes that the SC hire someone for this. The proposal says 1 person at a 50% level of engagement hired by the SC. Not sure how to make it clearer than that, but that's exactly what you propose isn't it?

@propensive
Collaborator
propensive commented Oct 31, 2016 edited

I think @Ichoran is just suggesting that the clause in the proposal suggesting that potentially several people could do the work (amounting to a total of 50% of one person) should be removed. I think the main thing is that there's one person who is accountable for it, even if he/she can delegate to others in the SC.

I actually don't think it should be that much work, but maybe I'm just being optimistic.

@Ichoran
Ichoran commented Oct 31, 2016

@propensive is right--while it sounds plausible to me that the only way to enact this proposal, if it was adopted, would be to hire someone specifically for the job (probably requiring additional funds for the center), my point is that there be a single point of responsibility no matter how much or little labor is dedicated to it. In some ways I think 0.1 of a single responsible FTE would be better than 0.5 FTEs of labor spread across several people none of whom are ultimately responsible for how things turn out. In other words, I think the "take charge" aspect is more important than the "do it" aspect.

@heathermiller
Collaborator
heathermiller commented Oct 31, 2016 edited

Proposals are for:

  • setting the goals of a project
  • deciding how much to budget towards the proposed project

The purpose of this 0.5FTE part of the proposal is budgeting. It's going too far for anyone other than EPFL to make a fine-grained decision on hiring or on how budget is spent on a specific project. That's not the place of the committee.

Correct protocol here should instead be discussing/deciding whether or not 1 person at 50% is the adequate amount financially to invest in this.

@soc
soc commented Oct 31, 2016

@Ichoran Why not ask people who have a proven track record of getting things done like @ochrons (Scala.js) and @charafau (Scala-on-Android) to assume some leadership role instead?

From my point of view the problem is that we have too many people that want to be in charge, and not enough people who take responsibility and get things done.

@Ichoran
Ichoran commented Oct 31, 2016

@soc - A Scala Center employee who was responsible for making it happen could delegate to someone else if that was the best way to get it to happen. I would leave it to the responsible party to make the decision about how to best accomplish this. (This is the whole point of having one responsible person.)

@heathermiller - I have a notoriously bad record for estimating how much effort something will take, so I'll leave the person-hours-of-investment discussion to others. My points are limited to: (1) One person in charge; (2) coordination/organization is valuable, not just doing it oneself.

@heathermiller
Collaborator

My points are limited to: (1) One person in charge; (2) coordination/organization is valuable, not just doing it oneself.

@Ichoran Thanks for the clarifications. I understand your points. I just have to point out here that while your points are useful, these points aren't for the proposal. The proposal should answer two questions:

  • what should we try to achieve? (list goals)
  • how much should we spend? (in FTE)

This is the information the committee needs to make a decision whether or not to allocate the proposed budget to the proposed project. The rest; details like management, hiring, etc, needs to be left up to EPFL (by mandate).

@Ichoran
Ichoran commented Oct 31, 2016

Okay, then I'd propose adding these goals:

  1. There should be strong community involvement in documentation not only to improve the documentation but also since this can strengthen the community and build a culture that views documentation, training, and usability as important.
  2. Members of the community should be able to get timely and authoritative advice and answers on all aspects of improving documentation, and it should be crystal clear how to find or solicit such advice and answers.

This is sort of suggested by "ongoing attention", but really, attention itself is an implementation detail.

@sschaef
sschaef commented Oct 31, 2016 edited

I don't disagree with the goal of this proposal to move maintenance responsibility but I disagree with the real outcome this proposal would have. This proposal only talks of "maintenance responsibility" but not of ownership, which is a mistake because these two things can't be separated.

It shouldn't be Scala Center who is seen as the maintainer of scala-lang.org but the Scala community itself. Scala Center does not speak for the Scala community - no one in the Scala Center has ever been elected in a democratic process to speak for the Scala community (except of Lars Hupel (@larsrh) who has been elected by the Typelevel community).

The misery right now is due to the fact that the leaders of Scala hold ownership of scala-lang.org but refuse to be the maintainer of this site. The leaders of Scala, as I see it, are Martin Odersky (@odersky) because he created Scala and the Scala team at Lightbend (led by Adriaan Moors (@adriaanm)) because the original Scala team at Typesafe also helped to create Scala. It is the duty of every owner to also be a maintainer if they want to get accepted by the community.

In order to resolve this misery I hereby ask the leaders of Scala to give up their ownership of scala-lang.org and transfer it to an independent and democratically elected entity whose sole goal it is to own and maintain scala-lang.org.

As long as such an entity does not exist the current problems of unmaintained content on scala-lang.org will never be resolved. The owners of Scala can state as many times as they want that they encourage contributions to scala-lang.org but the reality is that they won't receive more contributions in the long term because people want to have the feeling that their opinion has the same values as someone else' opinion.

Scala has changed drastically over the years. It has grown from a small community of people who used the language in their free time to a language that is used by millions of developers all over the world not only in their free time but also during their jobs. But while the Scala community has changed, the leadership hasn't. The diversity of interests within the Scala community that we can observe today can no longer be represented by the people that led Scala so far. The first step to change leadership is to give up ownership of scala-lang.org - after that the community has the power to decide in which direction they want to move and how they want to grow.

One of the largest clashes of interests has been expressed recently in The state of the website and documentation (Why I don't work on scala-lang.org&friends anymore) by Simon Ochsenreither (@soc). This thread is not just an expression of diversity of opinions - it is also an expression of denial of the current leadership. The current leaders of Scala can refuse to give up their ownership of scala-lang.org but if they do they should be aware that further clashes of interests will happen and they will happen more frequently than we see them today.

If however there is agreement that an independent entity for scala-lang.org shall be created here are my ideas to get there:

  1. The leaders of Scala publicly state that they want to give up ownership of scala-lang.org
  2. A new (non-legal) Github organization is founded. It could be https://github.com/scala-lang because this one doesn't exist yet.
  3. A proposal period is started where every member of the Scala community can be proposed as an owner of this Github organization.
  4. An election period is started among all the people who have been proposed and who have accepted the proposal.
  5. The N highest voted people will be granted ownership of the Github organization.
  6. The repos https://github.com/scala/scala-lang and https://github.com/scala/scala.github.com and maybe some others are moved to the new Github organization.
  7. Other things that require ownership like the scala-lang.org domain or communication channels, like the Scala twitter channel should also be given to the newly elected owners.
  8. The elected owners are now in full control of the content that is shown on scala-lang.org and where it is hosted. They can do whatever they think is best for the Scala community, after all that is what they have been elected for. They are allowed to to create content by themselves, start elections for maintainers of the site and it is especially their duty to ensure that the Scala code of conduct is applied on all communication channels that fall in their ownership area.
  9. Everyone who wants to contribute something to scala-lang.org has to open a PR and go through the usual Github model of contributions. This also includes previous owners of the site, i.e. when they want to publish blog posts for new Scala releases or blog posts about Dotty.

The world would continue to work in the way how we know it but the owners of scala-lang.org would be democratically elected, which means that the community can trust them. Owners would be relatively well known and respected people within the Scala community and while this doesn't guarantee that they are not doing "bad" things it would hurt their public reputation and therefore would be at least some kind of guarantee.

Two remaining problems:

  1. At the beginning there is a steward needed who creates the Github organization and is doing all the work of the first elections. This person at the beginning can't be elected of course, someone just needs to do it. If no one steps up I offer to do this work at the beginning. While I have no interest in being an owner of scala-lang.org I do have an interest that the front page for Scala can already represent a community where everyone has the same chances for their ideas to be appreciated. This works best for a community whose leaders are democratically elected. I also do have a lot of free time in the next months, which would allow me to do the busywork at the beginning, therefore this proposal shall not fail because we can't find someone who wants to get the ball rolling.
  2. There may be a lot of work to do and people are afraid that the work does not happen. free/libre software tells us that work will be done eventually, however. While I can't tell how many people there are that want to work on scala-lang.org, I believe that the main reason why rarely anything is done right now is simply because the site is not led by the community. The Typelevel community is a great example of why this model of a community works. If larger changes to scala-lang.org are required that need financial support (or simply bills that need to be paid) a proposal to Scala Center can always be opened in hope that financial support is given / someone is paid to do work. Other areas to make money can be donations for example. But this point most likely would require a legal organization and shouldn't be needed at the beginning.
@Ichoran
Ichoran commented Oct 31, 2016

@sschaef - I don't think this is the right venue to discuss such a proposal in depth (though it is perhaps an appropriate place to raise it, as "taking responsibility" and "giving up responsibility" are pretty much opposite courses of action).

In brief, though, I think you are underestimating the value of guaranteed support, and too quickly moving to a stance where Scala Center is assumed to not be a responsible custodian for works by the Scala community.

What examples do you have of languages where what is nominally the main web site and public face for a language is run by the community of that language sans major corporate players (which seems to be what you are advocating)? Some of us need to be sold that this is a great idea; you seem to be assuming it a little too much.

Just because someone is paid to improve something doesn't mean that the community can't contribute. Ideally, the paid person would be in a position to say, "You do this because you love it--great! I do it because I love it but in part I do the un-fun, tedious, irritating parts because I get paid to do it and you don't. I've got your back--you guys do the stuff that motivates you."

If that situation comes to pass it's better than what you propose, because you don't have to hope for free/libre software principles to come save you. (Plenty of free/libre software projects die, too, you know.)

If it's a good way to make progress, the custodians could very well run things similarly to you describe while providing the additional security of avoiding abuses and making sure that someone always has time to keep things moving.

@soc
soc commented Oct 31, 2016

What we don't need in my opinion is a continued shifting around of responsibilities, titles, job descriptions and discussions about fractions of FTEs.

This is just prolonging the organizational problems that caused the issues in the first place.

I want to have people in charge who take on responsibility (and actually do the work) because they believe user experience is import, not people who get paid to reinvent fixes/oversee fixes to a website – fixes that could have shipped a year ago, by the way.

If this is not the right place to have that discussion with the community, I suggest that people should point out an appropriate place for having that debate.

I would happily reconsider how the division between scala-lang.org and get-scala.org could be resolved under Simon's proposal with the right people in charge.

@adriaanm
Contributor

What we need is a civilized debate. Please stick to facts and criticism of ideas.

When you say stuff like

I want to have people in charge who take on responsibility (and actually do the work)

How does that contribute to the discussion?

@Ichoran
Ichoran commented Oct 31, 2016

@soc - What is the advantage of having people who care about user experience, but not necessarily Jekyll configuration or layout consistency or ease of testing modifications to the website on a local machine or sensitivity to the key issues for all different types of Scala users, be "responsible" for the entire thing? This means they must care about all aspects, not just user experience, whether they want to or not.

I think you are mixing up skepticism that a responsible party could deploy the work of an eager and motivated party with what it means to be responsible.

@dotta
dotta commented Nov 1, 2016

I like the intention of the proposal, but what I'm missing is a clear set of goals with a timeline. Without it, I don't see how you can conclude what is the effort needed, and hence how you can decide if 0.5 FTE is going to be enough/too little/too much to meet these goals. Also, I think it will be good for the person being hired to know the objectives against which she/he will be evaluated, as it will keep her/him focused.

@heathermiller
Collaborator
heathermiller commented Nov 1, 2016 edited

Hey @dotta, thanks for chiming in. As I read it, the goals listed in the proposal should guide this person's activities. Roughly as I read them from the proposal:

  • update outdated documentation
  • update and improve infrastructure
  • manage PRs/contributions from the community
  • help with comments/discussions on content (Disqus is not the best)

This person would be evaluated on whether they are making progress on achieving these goals in the first 3 months of part-time employment.

About timeline, good question. I think @SethTisue's proposal is that this is something that should be ongoing. Though, I'd imagine that in the advisory board meeting, we would discuss how long to try this out for. E.g., 1 quarter, 2 quarters, 1 year.

I guess the question is; (if we assume the goals listed above are what we want) should we propose that this be an ongoing thing? Or should we propose something we run for a pre-defined duration?

@dotta
dotta commented Nov 1, 2016

Hey @heathermiller, glad to hear the feedback is useful.

The way I read it, the listed goals are high-level objectives, but I think a plan of action is still needed. I'm guessing there are priorities in your mind (e.g., documentation that needs to be updated asap vs documentation that should be improved in the long run). Basically, I think it'd be beneficial for both the hired person and the Scala community to know what are the exact priorities.

Also, I believe an estimate of how much time is needed for maintaining the sites, the infrastructure, responding to PRs, engage with the community, will be useful. Hopefully, you have some data (activity in the past years) that you can use to project how much time these maintenance activities require each week or month.

For instance, in the first three months, how much time will be left for improving the state of the site if the same person also has to engage with the community? Or is engaging with the community a goal only after the sites are in good shape? There is a (context-switch) cost in having too many goals, so maybe focusing first on a few, well-defined, objectives may not be the worst idea.

I guess the question is; (if we assume the goals listed above are what we want) should we propose that this be an ongoing thing? Or should we propose something we run for a pre-defined duration?

It's definitely an ongoing thing. However, an important effort seems to be required at the beginning to catch up on work that has been neglected in the past years (not pointing fingers here, just saying there is work to be done).

@heathermiller
Collaborator

@dotta Thanks for your clarifications. If you think that the goals should be more precise, please let us know how you think things should be changed. Commenting in-line would maybe help.

@dotta
dotta commented Nov 1, 2016

@heathermiller Mine is a general remark, and I don't think it makes sense to inline comments. But I'll try to clarify my thoughts. For instance, In the proposal there is a paragraph saying:

All three sites have outdated content

Are all of the improvements for the three sites going to be taken at the same time? Is it expected that after 3-months all the objectives listed will be resolved? If not, then I think there should be a priority about what is to be tackled first, and by when all of the objectives listed in the document will be met.

Another example. In the proposal, it is said:

docs.scala-lang.org is the most neglected. Outdated content exists through the site. The single most important feature, the "Tour of Scala", frequently gets very negative feedback from visitors new to the language; it needs an overhaul. The look and feel of the site should be brought in line with scala-lang.org.

That seems to imply a pretty massive work. How is this work going to be carried out, i.e., what are the tasks and how are they prioritized wrt everything else. Are the tutorial for Ruby or Python ever going to come? Any other language? Basically, how is the documentation site going to change, what is the plan and timeline?

@SethTisue
Collaborator
SethTisue commented Nov 1, 2016 edited

Basically, how is the documentation site going to change, what is the plan and timeline?

Figuring that out (in consultation with the rest of the Center and the community) seems like part of the job to me. But honestly, a lot of the work that needs to be done, especially in the first 3-6 months is pretty obvious, and also, there is no shortage of existing issues, comments pointing out problems, and other community feedback from various sources on what needs improvement.

I agree that the budgeting situation is unclear and the 0.5 FTE number is arbitrary. My hope is that it's a high enough number to get some real work done, but a low enough number not to consume too much of the Scala Center's scarce human resources. It would be easy to have an entire team working on just this, if the Center could afford one.

@dotta
dotta commented Nov 1, 2016 edited

@SethTisue Without a timeline and a list of priorities, 0.5 FTE is good enough. For what? To do some work. On what? On some stuff. Even 0.1 FTE would be enough, you just need more time. My understanding is that the Scala Centre wants to figure out how much it should invest to reach the goals outlined in the document. Time has to be part of the equation. And, the moment you include time, I think you'll have to prioritise tasks and scope them.

@SethTisue
Collaborator
SethTisue commented Nov 1, 2016 edited

For what? To do some work. On what? On some stuff.

There are many specific work items in the proposal.

@dotta
dotta commented Nov 1, 2016 edited

For what? To do some work. On what? On some stuff.

There are many specific work items in the proposal.

@SethTisue Right. But @heathermiller said:

This is the information the committee needs to make a decision whether or not to allocate the proposed budget to the proposed project.

Without a timeline, I don't think you can take an informed decision. But that's just my opinion.

@dotta
dotta commented Nov 1, 2016

@SethTisue I've completely missed your edit on #11 (comment), and my comments after it were based on what you said before editing. Hence, I realize these comments now don't make much sense anymore :) And, I finally see how the 0.5 FTE budget was decided.

Sorry for the stream of messages. And, again, the vision does look great!

@ochrons
ochrons commented Nov 2, 2016

I support having a dedicated person looking after Scala documentation. Relying on "volunteer" work is not enough, since a lot of this maintenance work is quite boring, so nobody wants to do it.

For example I put a lot of effort into redesigning the scala-js.org website, including a lot of new content targetted at newcomers with JavaScript background. But once that was launched, I haven't really contributed to the documentation, even when there are a lot of things that would need improvement. This is quite natural.

If you look at the commits to scala,js website repo (https://github.com/scala-js/scala-js-website/commits/master) you will notice that vast majority of them are about updating the list of Scala.js libraries. Rest are Scala.js announcements by Sebastien :) This is in part because the list of libraries is very easy to contribute to, and people have an interest to see their own libs (or libs they use) there, Improving existing documentation or creating new, is a much larger undertaking, so it just doesn't happen.

Because valuable contributions (and contributors!) are exceedingly rare, they should be treated as gifts. You take it and say thank you, no matter how ugly the painting might be. Nitpicking over grammar, content or even small mistakes is a sure way to make sure they never contribute anything again. Just say "Thanks! I'll polish it a bit and merge", fix whatever needs fixing and be done with it. If there is something controversial, you still say thank you, polish it and merge, and then raise an issue with the relevant people, discussing if it should be changed somehow.

Now, as long as the documentation is mainly maintained by people like Seth and Heather who have a lot of other things on their plate, this won't really happen, so we need a dedicated person who has the time and (at least monetary) motivation to do this.

But just accepting contributions is not enough! They should be actively seeked and encouraged. For example crawling through StackOverflow Scala questions and picking good answers that would improve the documentation. And not ask the person to submit their answer to the doc, but to proactively take it, modify it and then ask the author to approve the change. This way you get people involved without any effort on their side. People feel good seeing their work on a prominent, official website! Once they are involved, they get more interested in directly contributing to the docs. You just have to give them that first free sample :)

Then there is the whole discoverability problem. Even great documentation is useless if people cannot find it. This again requires a very active and responsive approach, following sites like SO, Reddit and mailing lists for relevant questions and then supplying links to the docs in the answer. Over time these replies, comments and answers will contribute to improved visibility in relevant Google search results etc.

Same goes for more interactive channels like Gitter chats. The conversations need to be followed and appropriate actions taken when people need help and cannot find the relevant docs. It's also a great place to encourage people to contribute issues if not even changes to the doc site.

All of this obviously requires a person who does it continuously and in a pedantic fashion. It would be good to know some Scala, but not be an expert in it, so they can always go for the "Hey XYZ, could you help me with this doc as you're the expert on this matter and I'm not" -line to get people involved and feel good about themselves :) Also this keeps the person "detached" from the (sometimes heated) discussions on the content itself.

Basically when this person comes to work in the morning, they should ask themselves "What can I do today to make it even easier to contribute to Scala documentation and how can I get more people involved". The rest will follow naturally.

@SethTisue
Collaborator

@mircodotta my fault, I have a bad habit of editing my comments on GitHub in the moments after posting. cheers

@adriaanm
Contributor
adriaanm commented Nov 2, 2016

@ochrons thank you so much for writing that down -- I wholeheartedly agree. I wouldn't have thought of the various subtleties and strategies you point out. Thank you.

This passage especially stands out for me, and it made me realize we haven't always been the best accepters of gifts:

Because valuable contributions (and contributors!) are exceedingly rare, they should be treated as gifts. You take it and say thank you, no matter how ugly the painting might be.

@mdedetrich
mdedetrich commented Nov 2, 2016 edited

Im really on the fence on this one, I agree with both @sschaef and @ochrons, I think it comes down to what happens in reality and what is theoretically possible.

From what I have seen, in the past, having a single person owning responsibility of the website hasn't really worked. I don't want to put myself into a dogfight, but the impression I am getting is that people who had little time/passion were given responsibility for maintaining the site (which didn't appear to have as good as a desired outcome as we wanted as a community). This isn't meant to be a personal attack on the people involved, its just what I see. The design of the official scale-lang.org website is fantastic, but it hasn't really been updated with content which will push the language further (I am not just talking about the obligatory bumping of Scala version numbers when a new version is released). The content I am speaking of is broadly the stuff that @soc mentioned here https://groups.google.com/forum/?nomobile=true#!topic/scala-internals/r2GnzCFc3TY, don't necessarily agree with all of it but I agree with the general gist of what is listed there)

Unfortunately the thing is that having the site run by a committee (as what @sschaef is suggesting) is usually not that effective unless you handpick the committee very well but from a practical POV I am seeing it as the lesser evil which is more likely to provide better results from the community, at least as far as history goes.

I think what @soc, @sjrd and @ochrons have shown us is that if that someone is unencumbered by bureaucracy or decision making and they are passionate about a community process, we can make some very good websites (get-scala.org/scala-js.org/scala-android.org or all examples of this).

Also I would recommend people read https://www.reddit.com/r/haskell/comments/4zzmoa/haskellorg_and_the_evil_cabal/, basically the haskell community is going through almost the exact same problem we are now so I think its useful to learn from them as well.

@adriaanm
Contributor
adriaanm commented Nov 2, 2016

I think it's fair to say the website hasn't gotten the attention it needs, because of limits to available time. Having the Scala Center hire someone that has that time seems like a great solution to me. I'm speaking for myself here, but it seems the Scala Center can and should play to role of facilitator and organizer, enabling and empowering the community to contribute. This goes both ways of course – these contributions must be cherished as gifts – but they also should be offered with expectations that can reasonably be met.

@mdedetrich

I think it's fair to say the website hasn't gotten the attention it needs, because of limits to available time.

Yeah that is the general impression I got

Having the Scala Center hire someone that has that time seems like a great solution to me. I'm speaking for myself here, but it seems the Scala Center can and should play to role of facilitator and organizer, enabling and empowering the community to contribute.

I hope so, like I said I am on the fence. Historically speaking it hasn't been that successful and also I am not sure if this position is going to be permanent or temporary (this really does need to be a permanent position).

I hope I am wrong in this regard though

@adriaanm
Contributor
adriaanm commented Nov 2, 2016

I agree it's important to have continuity, and to encourage community contributions. Ultimately, that's what open source is about -- to open up the source for contribution. That said, I think there's value in a single person maintaining an overview and coordinating work towards a coherent set of objectives. It seems beneficial to at least actually try this (so far, the website has never been anyone's full-time or even half-time job). I don't see any reason to believe this person would be inhibited by bureaucracy.

@SethTisue
Collaborator

I made this small addition to the proposal:

+* The fate of the old wiki should be decided
+     * https://wiki.scala-lang.org is mostly outdated and could
+       be shut down
+     * But first someone should make a last pass over it and rescue
+       anything that may still have value

(I forget who reminded me about the old wiki: thank you.)

@stuhood
Contributor
stuhood commented Nov 29, 2016

@SethTisue : Having read through the other feedback, I think that the proposal should expressly mention as one of its Major Goals: "maintaining the channels of external contribution to the websites" (to attempt to summarize @ochrons' eloquent description).

With maintaining outside contribution as a Major Goal, it's possible that some of the other Major Goals could be accomplished via calls for community contribution.

@SethTisue
Collaborator
SethTisue commented Nov 29, 2016 edited

@stuhood agreed — and thank you @ochrons. I pushed e12bdbb which hopefully improves this

@propensive propensive merged commit aa4c756 into scalacenter:master Nov 30, 2016
@SethTisue SethTisue deleted the SethTisue:websites-proposal branch Nov 30, 2016
@SethTisue
Collaborator

This proposal was approved by the board. (Details in the minutes, which we'll publish as soon as we can.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment