docs: clarify contribution recommendations and add coding tips

mkdocs.yml

@@ -68,7 +68,11 @@ nav:
           - Overview: "opportunities/gsoc/index.md"
           - Project Ideas: "opportunities/gsoc/project-ideas/index.md"
           - "Contribution Guidelines": "opportunities/guides/contribution/index.md"
-          - "Candidates' Guide": "opportunities/gsoc/guides/contributor/index.md"
+          - "Coding Tips": "opportunities/guides/coding-tips/index.md"
+          - "Guides Overview": "opportunities/gsoc/guides/contributor/index.md"
+          - "Organization Admins Guide": "opportunities/gsoc/guides/organization-admins/index.md"
+          - "Mentors Guide": "opportunities/gsoc/guides/mentors/index.md"
+          - "Contributor Candidates Guide": "opportunities/gsoc/guides/candidates/index.md"
           - "Template: Project Idea": "opportunities/gsoc/templates/project-ideas.md"
           - "Template: Candidates Project Proposal": "opportunities/gsoc/templates/contributor-proposal.md"
   - Partnership:

pages/opportunities/gsoc/guides/candidates/index.md

@@ -0,0 +1,115 @@
+# GSoC Guide for Contributor Candidates
+
+These are Open Science Labs' (OSL) general recommendations for projects and
+sub-organizations participating in Google Summer of Code (GSoC) under the OSL
+umbrella. Organization admins and maintainers can use, adapt, or incorporate
+these recommendations partially or completely into their own project guidelines.
+Contributors: also read the guidelines of the project you are contributing to.
+Official GSoC rules and applicable codes of conduct still apply.
+
+## Start in the Community's Preferred Channel
+
+Find the project's preferred community app or channel and use it for your first
+contact. Introduce yourself, explain your interests, and ask:
+
+- Does the organization intend to participate in the upcoming GSoC edition?
+- Which of its projects or project ideas are planned to participate?
+- Where can I find the relevant documentation and discuss getting started?
+
+Ask about the team's plans for the upcoming GSoC edition rather than assuming
+participation based on a previous year. Choose a project that aligns with your
+interests, skills, and learning goals. Allow time for replies and keep technical
+questions in the community channel so others can learn and help.
+
+## Spend Time Using the Software
+
+Use the software as a user before rushing to change its code. Spend several days
+exploring it, follow the documentation, and try it on a real task or a need you
+understand. For a tool or library, test different contexts and use cases rather
+than stopping after one quick-start example.
+
+Discuss your experience with colleagues, other users, and the community. Ask
+questions, compare approaches, and understand why existing workflows work as
+they do. Keep notes about examples, strengths, confusing steps, and limitations.
+Hands-on experience helps you identify useful improvements and explain why they
+matter to users.
+
+## Write About Your Experience as a User
+
+Before opening a pull request, write a blog post or newcomer experience report
+covering:
+
+- The project's mission, main objectives, and intended users.
+- What you used it for, why you chose those tasks, and the contexts you
+  explored.
+- How to install or access it, with reproducible examples for other newcomers.
+- What works well and which features or workflows you found useful.
+- What was confusing, what could work better, and any setup or documentation
+  obstacles.
+- Constructive suggestions, questions discussed with others, and what you
+  learned.
+
+Take time to develop observations from actual use. Write an honest account with
+specific examples. Follow the announced submission process; a draft or Markdown
+document shared with the team is enough when public publication is not
+requested. If setup fails, document what you tried and where you became blocked.
+
+Then agree on a small follow-up contribution with a mentor, such as improving
+onboarding documentation, adding a test, or fixing a bug. Focus on useful work
+and responding to feedback rather than maximizing the number of pull requests.
+
+## Prepare Your Proposal
+
+Develop a detailed proposal with mentor feedback that explains:
+
+- **Impact:** How the work advances the project's goals and helps its users.
+- **Plan:** Specific tasks, deliverables, milestones, timeline, and risks.
+- **Availability:** Time commitments and planned absences.
+- **Newcomer Insight:** An observation from using the software and a suggested
+  improvement.
+
+Use clear, concise language. Follow the published AI-use policy, disclose
+assistance as required, and verify everything you submit. Write a proposal that
+reflects your own understanding and be prepared to explain your choices.
+
+Review the [official rules](https://summerofcode.withgoogle.com/rules), the
+selection checklist, and the
+[assessment rubric](../organization-admins/index.md#give-community-engagement-explicit-weight)
+before applying. Use the
+[proposal template](../../templates/contributor-proposal.md).
+
+## Review Process
+
+Notify mentors in the designated channel when your proposal is ready for review.
+Respond to feedback, ask clarifying questions, and allow time for replies. Show
+engagement through thoughtful discussion, useful progress updates, support for
+peers, and follow-through on agreed tasks. The recommended internal rubric gives
+community engagement 50% of the assessment and technical understanding and
+planning the other 50%.
+
+<a id="approved-contributors"></a>
+
+## After Selection: Work with Your Mentor
+
+Agree on weekly objectives, check-in times, reporting channels, response
+windows, and planned absences. Send a brief daily status report on agreed
+working days using a shared thread or project log. Include:
+
+- **Progress:** What I worked on or learned, with links where relevant.
+- **Next:** What I plan to do next.
+- **Blockers:** What is preventing progress and what help I need.
+
+Report blockers even when no code was completed, and give early notice of
+changes in availability. Ask for help, respond to reviews, and use feedback to
+improve your work. Follow the
+[Coding Tips](../../../guides/coding-tips/index.md) for readable code, focused
+pull requests, testing, and documentation.
+
+Consult the [GSoC Student Guide](https://google.github.io/gsocguides/student/)
+and Google's
+[advice for contributors](https://developers.google.com/open-source/gsoc/help/student-advice)
+for further application guidance.
+
+---
+
+See the [GSoC guide overview](../contributor/index.md) for all roles.

pages/opportunities/gsoc/guides/contributor/index.md

@@ -1,101 +1,50 @@
-# Google Summer of Code (GSoC) Contributor Guide
+# Google Summer of Code (GSoC) Guides
 
-This guide is intended for both prospective and accepted candidates of the GSoC
-program with Open Science Labs. It provides detailed, objective instructions to
-help navigate the application process, engage with mentors, and succeed during
-the program period. The guide covers project selection, initial contributions,
-proposal development, and expectations for approved contributors.
+These are Open Science Labs' (OSL) general recommendations for projects and
+sub-organizations participating in Google Summer of Code (GSoC) under the OSL
+umbrella. Organization admins and maintainers can use, adapt, or incorporate
+these recommendations partially or completely into their own project guidelines.
+Contributors: also read the guidelines of the project you are contributing to.
+Official GSoC rules and applicable codes of conduct still apply.
 
-## Candidates' Guide
+Choose the guide for your role. Each page contains the full recommendations for
+that role, with links to shared contribution and coding guidance.
 
-This section outlines the steps candidates should follow to apply effectively.
+## Organization Admins
 
-### How to Apply
+[Read the Organization Admins Guide](../organization-admins/index.md) to
+coordinate participation, mentor capacity, selection criteria, engagement
+assessment, and evaluation decisions across projects.
 
-#### Selecting a Sub-Organization/Project
+<a id="suggested-practices-for-mentors-and-sub-organizations"></a>
 
-Candidates should begin by reviewing the list of available sub-organizations
-under Open Science Labs and their projects. It is important to choose a project
-that aligns with individual interests and skills.
+## Mentors
 
-#### Initiating Contact with Projects and Mentors
+[Read the Mentors Guide](../mentors/index.md) to prepare project guidance,
+welcome and assess candidates, publish AI policies, set expectations, and
+support contributor progress.
 
-Candidates are advised to contact project mentors using the recommended
-communication platform (discord, slack, email, etc). A brief introduction,
-expression of interest, and any initial questions about the project or mentoring
-process should be included. Each project or sub-organizations should specify the
-recommended platform for all the communications with candidates.
+<a id="candidates-guide"></a>
 
-#### Making an Initial Contribution
+## Contributor Candidates
 
-Demonstrating commitment early on is valuable. Candidates are encouraged to
-contribute a small but meaningful improvement—such as fixing a minor bug or
-implementing small features suggested by the mentor.
+[Read the Contributor Candidates Guide](../candidates/index.md) to contact the
+community, explore the software, write about your experience as a user, and
+prepare a proposal.
 
-#### Crafting a Proposal with Mentor Support
+<a id="review-process"></a>
 
-Under mentor guidance, candidates should develop a detailed proposal that
-outlines:
+For application review, see the
+[candidate review process](../candidates/index.md#review-process).
 
-- **Milestones and Timeline:** Specific tasks and expected outcomes within the
-  program period.
-- **Contribution Impact:** How the work will further the project’s goals.
-- **Language and Style:** Clear, informative, and objective language; concise
-  and focused content without unnecessary filler or marketing-style phrasing.
+<a id="approved-contributors"></a>
 
-Candidates should also ensure that proposals do not exhibit signs of complete AI
-generation, such as excessive buzzwords or generic phrasing. While AI tools may
-be used to enhance clarity, the proposal must reflect the candidate’s own work.
+After selection, follow the guidance on
+[working with your mentor](../candidates/index.md#after-selection-work-with-your-mentor).
 
-It is essential to review the
-[contributor rules](https://summerofcode.withgoogle.com/rules) for the program
-and follow the proposal template provided
-[here](/opportunities/gsoc/templates/contributor-proposal).
+## Shared Guidance
 
-## Review Process
-
-Mentors will evaluate proposals to determine if candidates meet the fundamental
-requirements for effective contribution. Transparent feedback will be provided,
-and candidates may be guided to consider alternative projects if a better fit is
-identified. When a proposal is ready for review, candidates should send a direct
-message to the mentors via the recommended communication channel (e.g., Discord,
-Slack, or email). For all other communications, public channels are preferred.
-Candidates should remain patient as mentors manage a high volume of messages,
-issues, pull requests, and reviews.
-
-## Approved Contributors
-
-For accepted candidates, the following guidelines serve as a roadmap for
-successful collaboration during the GSoC program with Open Science Labs.
-
-### Effective Workflow and Proactivity
-
-- **Establish a Regular Workflow:** Work closely with your mentor to set clear
-  weekly objectives.
-- **Proactive Engagement:** Actively seek tasks, ask clarifying questions, and
-  schedule regular check-ins to monitor progress.
-
-### Communication Best Practices
-
-- **Timely Updates:** Keep mentors informed about progress, challenges, and any
-  required assistance.
-- **Use Designated Channels:** Communicate via the project’s preferred platforms
-  to ensure transparency and prompt feedback.
-
-### Programming Best Practices
-
-- **Adherence to Standards:** Follow the coding standards and best practices
-  outlined by your mentor and project guidelines.
-- **Maintainable Code:** Write clean, well-documented, and maintainable code.
-- **Constructive Feedback:** Embrace code reviews as opportunities to learn and
-  improve your technical skills.
-
-## Proposal Resources
-
-Candidates are encouraged to consult the
-[GSoC Student Guide](https://google.github.io/gsocguides/student/) for
-comprehensive details on the application process and proposal preparation.
-Additional recommendations can be found
-[here](https://developers.google.com/open-source/gsoc/help/student-advice). For
-further guidance, refer to the suggested proposal template available
-[here](/opportunities/gsoc/templates/contributor-proposal).
+- [Contribution Guidelines](../../../guides/contribution/index.md): community
+  engagement, task coordination, and reviews.
+- [Coding Tips](../../../guides/coding-tips/index.md): readable code, focused
+  pull requests, tests, documentation, and AI-assisted work.

pages/opportunities/gsoc/guides/mentors/index.md

@@ -0,0 +1,116 @@
+# GSoC Guide for Mentors
+
+These are Open Science Labs' (OSL) general recommendations for projects and
+sub-organizations participating in Google Summer of Code (GSoC) under the OSL
+umbrella. Organization admins and maintainers can use, adapt, or incorporate
+these recommendations partially or completely into their own project guidelines.
+Contributors: also read the guidelines of the project you are contributing to.
+Official GSoC rules and applicable codes of conduct still apply.
+
+## Prepare the Project and Welcome Candidates
+
+Publish the preferred community app or communication channel, contact details,
+and expected response times alongside the project idea. Explain the project's
+mission, intended users, main workflows, and development setup. State which
+ideas are planned for the upcoming GSoC edition and update candidates when plans
+change.
+
+Provide a manageable starting workflow and examples of helpful contributions,
+including documentation, tests, and bug fixes. Encourage candidates to spend
+several days using the software before rushing into a pull request. For a tool
+or library, suggest different use cases and realistic tasks so candidates can
+understand both its strengths and its limitations.
+
+## Use a Project Experience Report as the First Contribution
+
+Ask candidates to write a blog post or newcomer experience report from a user's
+perspective. Use it as an initial selection criterion and announce the expected
+effort, deadline, submission channel, and assessment criteria in advance.
+
+Assess what the candidate tried, how clearly they explain the software, what
+they learned, and the usefulness of their observations. Value reproducible
+examples and constructive suggestions. Accept a Markdown document or draft
+shared with the team without requiring a personal blog or a pull request. If
+setup fails, review the steps attempted and the blocker, and help the candidate
+move forward.
+
+Keep the task manageable and give candidates time to explore. Do not require a
+long history of contributions; use the activity to help newcomers develop and
+demonstrate understanding.
+
+## Publish a Project Selection Checklist
+
+Align project criteria with the
+[organization's selection framework](../organization-admins/index.md#publish-the-selection-framework).
+For example:
+
+- [ ] The applicant meets the current official GSoC eligibility requirements.
+- [ ] The project experience report meets the published criteria.
+- [ ] The proposal explains the project's goals and includes the requested
+      sections.
+- [ ] The candidate follows the published AI-use and disclosure policy.
+- [ ] The candidate shows meaningful engagement and responds within agreed
+      windows.
+- [ ] Availability and proposed scope are realistic for the project.
+
+Include a small, explicit, project-relevant instruction to check that candidates
+read the guidance. Request a "Newcomer insight" proposal section with one
+observation from trying the software. Include it in the instructions and
+checklist, and explain how omissions are handled. Use the response to discuss
+the candidate's experience and understanding.
+
+## Make the AI Policy Specific
+
+Explain permitted and prohibited uses separately for proposals, experience
+reports, code, tests, and documentation. State whether editing, translation,
+brainstorming, or code generation is allowed; what tools or data restrictions
+apply; and how assistance must be disclosed. Link the policy from the project
+idea, proposal instructions, and contribution guide.
+
+Assess understanding through the work and discussion. Describe how suspected
+violations will be reviewed and let candidates explain their work. Writing style
+alone is not evidence of AI use.
+
+## Review Proposals and Agree on Expectations
+
+Assess proposals using the published checklist and
+[assessment rubric](../organization-admins/index.md#give-community-engagement-explicit-weight).
+Provide clear feedback and discuss alternatives when another project is a better
+fit. Look for thoughtful questions, responses to feedback, useful observations
+from using the software, and follow-through on agreed tasks.
+
+Share a contributor checklist before selection covering deliverables, reporting
+frequency, response windows, check-ins, AI policy, review participation, and
+evaluation criteria. State your own availability, review turnaround, and backup
+contact. Explain what happens when expectations are repeatedly unmet.
+
+Confirm the working agreement during community bonding, including time zones,
+planned absences, and any adjustments. Keep a shared record of changes.
+
+## Support Progress and Address Problems Early
+
+Set clear weekly objectives, hold regular check-ins, and review daily status
+reports on agreed working days. Respond to requests for help and give actionable
+feedback. During selection, announce any reporting exercise in advance and limit
+it to a short, defined activity.
+
+If progress or engagement falls short, discuss specific examples privately,
+identify blockers and gaps in mentoring support, and agree on next steps and a
+review date. Distinguish persistent failure to follow through from an agreed
+absence or a technical obstacle raised promptly.
+
+Decline candidates who do not meet published selection criteria. During the
+program, give an honest failing evaluation when agreed expectations remain
+unmet; passing someone solely to avoid a difficult conversation helps neither
+the contributor nor the project. Coordinate with organization admins, document
+the basis for the decision, and follow the current GSoC evaluation process.
+Communicate concerns early and provide feedback before the evaluation.
+
+For official mentoring guidance, see
+[Setting Expectations](https://google.github.io/gsocguides/mentor/setting-expectations),
+[Selecting a Contributor](https://google.github.io/gsocguides/mentor/selecting-a-student),
+and [Evaluations](https://google.github.io/gsocguides/mentor/evaluations).
+
+---
+
+See the [GSoC guide overview](../contributor/index.md) for all roles.