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

[Stephanie Leary]

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-6457)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20230609/f67a4366/attachment.htm>