[Evergreen-dev] New devs onboarding: discussion items for Tuesday

Fri Jun 9 13:34:39 EDT 2023

Hi!

Thank you for raising these questions Stephanie! I don't plan to
participate much in the developer community, but I did have some
insight/feedback on a couple of questions you raised.

> At the conference, I asked everyone to look at the wiki home page,
> pretending that you are a newcomer. Some questions I think the wiki home
> page should answer:
> * What is Evergreen?
> * What does it take (broadly speaking) to install and manage Evergreen?
> * Where do I go for discussion about Evergreen?

I think the intent at the time was for the front page of the WordPress site
at https://evergreen-ils.org/ to provide the big picture of what Evergreen
is, where the communication channels are, etc. I'm not saying it was the
right decision, but I think that's why the front page of the wiki does not
directly address those questions.

IRC is a barrier to entry for newer developers. I know there is a Gen X
> nostalgia factor here, but we need to seriously consider moving to Slack.
> It would be great to have channels for each of the interest groups, for
> example.

Even if we stay in IRC, there is an issue with the visibility of channels
> other than #evergreen itself. I did not know there was a separate channel
> for release discussions until Andrea mentioned it a while back. I still
> cannot find it in the server channel list–is it unlisted?–and as far as I
> can tell there is no mention of it in the wiki.

I don't have an opinion on IRC vs Slack and, full disclosure, do not plan
on using either very often when I'm back in the community. But I do have a
strong opinion on separate release channels. I have never been a fan of
multiple IRC channels for the community. I think it all should be discussed
in the #evergreen channel. I don't know if the release channel existed
before the 2.12 release, but I never used it during that release cycle. I
have a vague memory of being pretty far into my tenure as 2.12 release
maintainer  when I learned about the channel, which explained why I often
seemed to be unaware of what was happening with the timing for my own point
releases. I would also say that the reason I so easily stepped into the RM
role was that I had always paid attention to the discussions that were
happening around releases back before there was a separate release channel.
It also serves the purpose of getting non-release-team folks involved in
the process if help is needed.

I also was not in favor of the special IRC channel we had when mentoring an
intern through the Outreachy program. I think those channels get created
out of concern there will be too much noise in the #evergreen channel, but
I've found secondary channels just silo discussions. If you're on IRC or
any other real-time chat service, you learn how to deal with the noise from
discussions that don't pertain to you. There have been times we created
temporary IRC channels for discussions that need to remain confidential,
such as selecting final interns through Google Summer of Code or Outreachy.
Those are the only cases where I see a need for them. Just my two cents for
whatever it's worth.

Happy Friday!
Kathy
--
Kathy Lussier
https://kmlussier.com
24 days away from having an official reason to weigh in on Evergreen issues

On Fri, Jun 9, 2023 at 12:26 PM Stephanie Leary via Evergreen-dev <
evergreen-dev at list.evergreen-ils.org> wrote:

> Happy Friday, everyone! I have a series of items on Tuesday's developer
> meeting agenda relating to the new developer onboarding experience, as I
> mentioned briefly in my lightning talk at the conference. I went to jot
> down my thoughts, and when my Google doc hit its third page, I thought
> perhaps I should send this out ahead of the meeting to give everyone time
> to digest.
>
> We have at least two organizations looking to hire Evergreen developers,
> and I know of a third that might be posting something in the near future,
> so this seems like a good time to talk about what it's like to join this
> project without previous experience in this community.
>
> *Wiki organization*
>
> At the conference, I asked everyone to look at the wiki home page,
> pretending that you are a newcomer. Some questions I think the wiki home
> page should answer:
> * What is Evergreen?
> * What does it take (broadly speaking) to install and manage Evergreen?
> * Where do I go for discussion about Evergreen?
>
> I think it's pretty hard to answer all of these on the current wiki home
> page. (For fun, search this page for the word "library.") It would be fine
> to copy some things from the docs; I will note that “Evergreen End-user
> Documentation” is a bullet point halfway down the wiki home page with no
> elaboration.
>
> Old stuff needs to be moved out of the way and clearly marked as archival
> or of historical interest.
>
> The code/language page is seriously intimidating, and needs to be
> rewritten so that it is clearer which languages are necessary to work on
> specific parts of Evergreen: the OPAC, the newer staff interfaces, and
> sysadmin tasks all have different requirements. A newcomer needs to be
> reassured that they do not have to be masters at ten different languages. https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:code
>
>
> The New Devs sidebar has an outline of the developer documentation we are
> working on; it would be great to have contributions from not-new devs: https://wiki.evergreen-ils.org/doku.php?id=newdevs:start
>
>
> *IRC channel findability*
>
> IRC is a barrier to entry for newer developers. I know there is a Gen X
> nostalgia factor here, but we need to seriously consider moving to Slack.
> It would be great to have channels for each of the interest groups, for
> example.
>
> Even if we stay in IRC, there is an issue with the visibility of channels
> other than #evergreen itself. I did not know there was a separate channel
> for release discussions until Andrea mentioned it a while back. I still
> cannot find it in the server channel list–is it unlisted?–and as far as I
> can tell there is no mention of it in the wiki.
>
> Obviously I could have asked for its name at any time, but I wanted to
> make a point of going through the 3.11 release without it, just to see what
> that was like. Here’s how things went down from my point of view:
>
> *  A couple of months ago there was a call for more participation in the
> release cycle.
> * Bugs got targeted for 3.11, work got done, things got discussed in
> #evergreen.
> * Then the conversation in #evergreen went DEAD SILENT for two weeks.
> * 3.11 appeared as if by magic.
> * Conversation in #evergreen slowly resumed.
>
> I have absolutely no idea how a new developer is supposed to learn about
> the release process or get involved in it.
>
> I would like to ask someone to take on the job of laying breadcrumbs from
> the wiki home page to some documentation about how releases happen and
> where that discussion is taking place.
>
> *Inline documentation*
>
> The lack of inline documentation is a serious problem for new developers.
> I have really struggled to figure out how data gets into big display
> components like eg-tree and eg-grid. It’s also hard to figure out which
> modules need to be included to make various things happen.
>
> I think we need to pick an inline documentation style, dump some empty
> boilerplates at the top of every custom module, and start filling things in
> as we can. I know of ngDoc, but there might be other good candidates. https://medium.com/@askoropad/ngdoc-documentation-for-angular-projects-3f6ea8fc22b0
>
>
> Some object references in the wiki would also be very helpful, especially
> anywhere the word “fleshing” appears.
>
> *Code standards*
>
> https://wiki.evergreen-ils.org/doku.php?id=code_formatting_standards is a
> little sparse. Are there parts of https://github.com/airbnb/javascript or
> some other well-established standard that we want to reference or borrow?
>
> *VSCode*
>
> Many of our experienced developers are command line warriors. Respect!
> However, a lot of our newer developers use VSCode, and we need more
> guidance on how to set up the project workspace and which files can safely
> be ignored.
>
> VSCode is free and available for Linux as well as Windows and Mac, so it
> would be great if we could get a few more experienced developers to
> experiment with it and help out with some setup documentation. The New Devs
> group has a suggested list of extensions here:
> https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:tools
>
> *In summary*
>
> Evergreen is an especially complicated and opaque project. It's
> extraordinarily difficult to join without having some kind of prior
> experience in the community. I know everyone is stretched thin, but helping
> new developers figure out how things work is going to help us all
> distribute the workload more evenly in the long run.
>
> I will be happy to talk more about this on Tuesday and to partner with
> anyone who wants to take on some of the to-do items I've described. (As
> long as it's after the ALA conference.)
>
>
> Stephanie Leary
> Front End Developer
> Equinox Open Library Initiative
> stephanie.leary at equinoxOLI.org
> https://www.equinoxOLI.org
> phone: 877-OPEN-ILS (673-6457673-6457673-6457673-6457)
> _______________________________________________
> Evergreen-dev mailing list
> Evergreen-dev at list.evergreen-ils.org
> http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20230609/f5b2a1fe/attachment-0001.htm>