LFX proposal: Improve documentation build infrastructure

[craigbox]

This issue relates to an LFX mentorship project for Term 3, 2024. Please feel free to comment on this issue about how we might improve the proposal, but commenting here is not the same as applying to LFX.

• Description: The build infrastructure for istio.io currently carries a complete archived copy of the site for each release of Istio. These archived versions should be separated to their own branch, with only the supported versions published. We should also separate out content which is not version-specific (e.g. the home page, news and blogs) so that only the latest version of this content is visible online.
• Expected Outcome: Updated publishing infrastructure for istio.io to separate evergreen content (home page, blogs) with versioned content (documentation). Add a method to allow switching between the supported versions (e.g. a drop-down on each docs page)
• Recommended Skills: Release management, systems engineering, scripting, programming (Go/Bash), Git, Hugo templating

Please note this project would best suit a graduate student with an interest in DevOps/systems engineering, as opposed to an undergraduate who is looking to learn to code.

Dos and don'ts for applying for this mentorship

• An LFX mentor is effectively a "hiring manager" and you're effectively applying for a job. Dozens of other people are applying too. Consider this in your interactions.

  • You want to stand out, but the mentor doesn't have bandwidth to coach everyone on how best to stand out.
  • There is lots of guidance on "how to write a cover letter" online. When you're applying for a job, researching the hiring manager is sensible; calling them beforehand to introduce yourself is not!
  • There are normally enough applicants that the mentor can drop all the CVs of people who didn't even write a cover letter.
  • Posting something generic about your interest on the LFX project issue or the project GitHub issue is not helpful. Apply through the portal when it opens.
  • An application that hints you have applied to every mentorship is standing out for the wrong reason.
  • A LinkedIn request that says "The idea of [COPIED AND PASTED PROJECT DESCRIPTION] is quite exciting & I'd love to contribute more to this" is bad too. What we hear is "you want a job".

• If you're reaching out to the mentor privately, please remember that open source is largely done in public. Any requests for more clarification about the project can be raised and resolved in public. Everything else should go in the application packet.

• Jumping into issues in the community is a great, but it is very obvious to maintainers when someone is doing it to try to win a paid mentorship.

  • Proposing a fix for an issue is a good way to hint that you would be a capable candidate.
  • Take a look at the cultural norms in the community before jumping in. Don't go around trying to /assign yourself to issues that the mentor created when the community doesn't have a culture of claiming issues by assignment.
    • Don't ask if you can work on a "good first issue". Just assume you can. Worst case, two people send a PR at the same time, and you learn from each other.
    • Commenting "I would like to do this" can come across as cookie licking.
  • Most open source maintainers are paid. Very few people do free work on a project they don't use. Remember you don't have to do free work for a company to get a job there and you are not required to do free work on an OSS project to gain a mentorship. It's OK not to have had time.
  • That said, do realise that lots of people do free work on OSS projects for lots of reasons!

• Make sure your application communicates why this project in particular is interesting to you. CNCF software is niche - it's not web sites or mobile apps - so have a good story as to why you are applying here, in particular.

  • We know you are going to be paid and that's OK. Students don't tend to use cloud server software, so it's understood you are applying because you want to be paid or you want to gain skills in a certain area.
  • "I would like to find work in the field of X" or "I would like experience in doing Y to round out my skills" are complete sentences, but you should also explain why
  • If you "just want to get involved in open source", hack on a project you use yourself.
  • Be realistic about the number of projects you apply to. Remember, low-effort applications are discarded immediately.

In the past, winning candidates have demonstrated their understanding of the project, proposed a solution, and set out how they will manage their time on the project. A candidate that turns up and shows they can add immediate value to the project, might even get a mentorship slot created exactly to their specification in the next cohort.

[asr2003]

Hey @craigbox ! Are there any recommended communication channels to connect with community?

It has not yet been accepted

I think now can be updated to accepted :)

I have been part of knative docs community and contributed to different designs and enhancements of upcoming release. I will go through the istio docs and will share any enhancements can be added to improve the proposal.

[craigbox]

PR in "proposed project list" does not equate to "accepted and loaded into LFX for applications".

I'll update this issue in a day or two with a "dos and don'ts about applying to Istio projects", but I would suggest that finding out how and where to ask good questions is a key part of demonstrating skill as an applicant!