Community.o Workshop @ EuroLLVM 2024

Community Community.o
4

My table was one of the 3 newcomer paths tables.

WHAT DID WE TRY TO FIND OUT?

We attempted to identify newcomer pain points, and attempted to find a way to improve the following flow:

  1. Newcomer begins writing code
  2. They get stuck
  3. They get themselves unstuck somehow (???)
  4. They finish their code, push code to GH

We focused on point (3) in the list.

WHO WAS AT THE TABLE?

Newcomers at the table worked primarily in MLIR and the LLVM backends.

WHAT DID WE LEARN?

… WE NEED TO WRITE MORE DOCUMENTATION :frowning:

Newcomers at the table expressed issues with documentation. In particular, they struggled with:

  • Finding existing documentation/tutorials on high-level concepts
  • Understanding documentation on detailed technical concepts, such as the backends, tablegen, etc.

In particular, a common trend in LLVM projects is that we often rely on what’s effectively oral history from experienced developers down to newcomers. In general, if a newcomer can be paired up with an experienced developer in an appropriate environment, they learn quickly and rarely get stuck.

Newcomers starting out outside of companies and schools that are lucky to have such experienced developers struggle finding out what they need to know.

… OFFICE HOURS CAN BE INTIMIDATING :frowning:

We have attempted to bridge this gap using, for example, office hours. Office hours are events in which an experienced developer volunteers their time to the community, and allows anyone to call in and ask them questions about LLVM.

In general, we agreed that the office hours are useful, but:

  • Discoverability is low
  • Some newcomers may be intimidated and feel as if they are going to “waste someone’s time”

… WE NEED TO UPDATE OUR DOCUMENTATION :frowning:

Certain parts of our documentation, such as the backend, can be out of date or confusing to developers.

… WE NEED TO IMPROVE DISCOVERABILITY OF OUR EXISTING DOCUMENTATION :frowning:

High level concepts, such as “how does LLVM work” are technically already documented, but you have to look for them.

For example, I just tried to find the “high level breakdown of LLVM” and the current best docs we seem to have directly from the docs page are Chris Lattner’s original writings from graduate school.

Technically our docs website has search functionality, but it doesn’t work too well.

We also have beginner tutorials from past conferences but:

  • There are a lot of them
  • It’s not clear which ones are intended for complete newbies versus experienced developers learning about a new piece of LLVM tech
  • The ones that are probably useful are not obviously linked in the documentation

… WE NEED TO MAKE IT EASIER TO UPDATE THE DOCUMENTATION :frowning:

Beginners expressed frustration with updating the documentation.

Particular complaints were:

  • Sphinx is frustrating to work with, they would prefer Markdown. (Note that some of our documentation is already written in Markdown. Example here.)
  • Newcomers would be more inclined to update docs as they run into trouble if it was easy to edit the documentation directly from the page. For example, if we embedded “edit on GitHub” links in the documentation, it would lower the amount of effort to fix/update documentation.

… WE NEED MORE INCENTIVES TO DO “BORING WORK” :frowning:

  • Many experienced developers are often employed to work on LLVM, and their companies often pay them to do specific work, that often does not include documentation. These developers may not work on LLVM outside of working hours.
  • There is little public recognition for doing “boring work” like documentation, office hours, and so on. We should reward people better for doing this sort of work.

… WE NEED TO HELP BEGINNERS ASK THE RIGHT QUESTIONS :frowning:
Some newcomers expressed frustration with asking questions on Discord/Discourse about certain topics and not getting replies.

This often happens when

  1. Nobody knows the answer to the question
  2. The question lacks necessary context for someone to answer it accurately

WHAT DO WE DO WELL RIGHT NOW?

WHAT CAN WE DO TO IMPROVE THE SITUATION?

… WHAT DOES OUR IDEAL “GETTING UNSTUCK” FLOW LOOK LIKE?
From the above complaints, we can say that if we can make the following flow more likely, we’ll reduce newcomer frustrations with the project:

  1. Newcomer writes some code
  2. Something is broken.
  3. Newcomer consults the documentation. If they find the answer to their question, they are done.
  4. If not, the newcomer goes to Discord or Discourse, and asks a question. A more experienced developer helps them.
  5. The newcomer fixes their code
  6. The newcomer improves the existing documentation, so that future developers do not run into the same issue

… HOW CAN WE GET THERE?

  • We could restructure LLVM’s documentation in the form of a Rust-style book. Notice in particular that each page in the book has a link to the associated GitHub repo, making it clear to know where/how to edit the docs.
  • We can write some documentation or a template on how to write a good question.
  • We can identify pieces of documentation that are out of date and known to be incorrect, and update them
  • We can identify the most common repeated questions from developers on Discord and Discourse, and see if we can prevent the repeated questions through documentation

… HOW DO WE BETTER RECOGNIZE “BORING WORK”?

  • We could have a “developer of the month” sort of thing which recognises members of the community who are doing a lot of community work
  • We could encourage employers to reward employees for doing “boring work”-- it improves their engineers’ standing in the community, and makes it easier for more people to contribute to LLVM. In theory, they rely on LLVM in some way, so encouraging their people to help others write quality code + maintain that project ought to be good for them too.
6 Likes