{{Header}} {{title|title= First-Time Documentation Contributor Policy }} {{#seo: |description=Guidelines and expectations for first-time documentation contributors to ensure a smooth and respectful collaboration experience. }} {{policy_mininav}} {{intro| This page outlines our expectations for first-time contributors to the documentation of this project. It's designed to keep the documentation process productive and respectful of everyone's time - yours and ours. }} == Getting Started == We love seeing new contributors join the project. To make the most of your first contribution, we recommend: * '''Start with documentation:''' The best introduction is a small, accurate documentation improvement. * '''Keep it simple:''' Fix something straightforward such as a typo, unclear wording, or a broken link. * '''Be self-guided:''' Your first contribution should be self-contained and require minimal discussion beforehand. == Requirements == * '''Use of Git:''' Documentation contributions that are maintained in git repositories must be made using the git version control system (not the GitHub web editor). * '''Preview your changes:''' You should be able to review your documentation changes yourself (for example by previewing the rendered output) without requiring step-by-step help. * '''No AI policy:''' Contributions cannot be purely AI-generated. AI-generated content must be clearly marked as such, as per [[Policy_On_Artificial_Intelligence|Policy On Artificial Intelligence (AI)]]. AI might be useful for reviewing your documentation, but you must still write and understand your own text. == GitHub Web Editor Contributions == * '''No GitHub Web Editor based contributions:''' First-time contributions should be made via the git command line and not via the GitHub web editor interface. Exceptions may be granted in rare cases. '''Rationale:''' In some cases, we have seen misuse of GitHub web editor + AI tools to submit low-effort, inaccurate, or misleading changes. Using git directly helps show genuine intent and familiarity with the contribution process. * '''GitHub Pull Requests:''' Optional. Permitted. Any git branch anywhere is permissible. == Exemptions == This policy is intended for new contributors who have not yet demonstrated prior experience or familiarity with the project's documentation practices. You may be exempt from the first-time contributor policy if you meet any of the following: * '''Public verifiable skills:''' You have a public history of documentation or technical writing contributions (e.g. documentation pull requests, wiki edit history, manuals, guides, or other writing samples that demonstrate moderate to advanced documentation skills). ** '''Verification required:''' Simply claiming to be someone is not sufficient. Evidence is required to verify identity and prevent impersonation. See footnote for acceptable verification options. Verification is not yet governed by a fixed policy and may evolve over time. However, many reasonable methods are currently acceptable, including: * '''Social media-based:''' Posting a verification message from a known social media account (e.g. a tweet or direct message from your Twitter/X profile). * '''Signed message:''' Sending a signed message using OpenPGP from a key known to be associated with you. * '''Email-based verification:''' Emailing from an address associated with your past contributions (e.g. one used in your git commit history). * '''Forum + git match:''' Using a forum or project account that uses the same email address as your git commits. * '''Past contributors:''' You have previously contributed to this project under your current identity. * '''Bypass via documentation:''' No verification is required if you submit a high-quality, self-contained documentation contribution. == Not Considered Valid Exemptions == * '''Claiming anonymous past contributions:''' Claims of past contributions under anonymous or pseudonymous identities that cannot be verified. * '''Non-documentation activity only:''' Prior contributions limited to issue comments, suggestions, or other participation without documentation improvements. == Why This Policy Exists == This policy is not meant to gatekeep contributors - it is here to protect everyone's time and ensure the project stays focused and sustainable. * '''Extended discussions without documentation:''' In Open Source, it's common for well-meaning users (and sometimes trolls or bots) to engage in long conversations without ever submitting documentation improvements. * '''Documentation contributions require initiative:''' While general questions are welcome in discussion channels, documentation contributions demand accuracy, follow-through, and independent effort. * '''Idea nudging without action:''' We've seen cases where people unintentionally nudge maintainers into writing documentation through vague suggestions or persistent questioning - without offering concrete edits. * '''Time cost for maintainers:''' These exchanges often take more time to respond to than it would take to write the documentation ourselves, reducing time available for actual maintenance. * '''Contributing is difficult:''' Most people cannot perform heart surgery. Even a doctor who does not specialize in it may not be able to perform it. There is no shame in that. To help explain this dynamic, here's a quote: {{quotation |quote= [...] Contributing to open-source can be great. You should do it because you're actually really interested in one particular project, like it's something you actively use, and you'd like to contribute your own skill to making it better. If you do it, the rule of thumb is that you should be able to review and validate your documentation changes without assistance, and you should be able to find a documentation issue that you can actually make some progress towards fixing on your own, before you should consider reaching out offering to help. For the projects I've maintained, for every 10 people who offer to contribute, I'm lucky if 1/10 actually manage to contribute anything, and even then most people leave after one contribution. Only a small fraction stick around to actually create more value than they took. The others have the best of intentions. But because they're beginners, they have trouble understanding the documentation structure, so we help them. Then they have trouble validating changes, so we point them in the right direction. Then they struggle to figure out how to improve clarity without introducing mistakes, and eventually give up because the topic is a lot more complex than anything they've ever worked on before, and they're just not ready. So it ends up being several hours wasted on our end, teaching a beginner some skills, and we get nothing out of it, because they lose interest. And that's taking away time that we could have spent making that project better. We only have so much time - whether paid time (if we work on the project for some company) or free time (if this is a passion project). [...] |context=https://www.reddit.com/r/learnprogramming/comments/1gtxwbz/how_do_i_prepare_myself_for_a_open_source/ }} This is a common issue: * [https://www.reddit.com/r/learnprogramming/comments/10v709r/im_finding_it_difficult_to_start_contributing_to/ Beginner struggles with contributing (reddit)] * [https://goauthentik.io/blog/2024-03-07-why-contributing-to-open-source-is-scary/ Why contributing can feel scary] * [https://antirez.com/news/129 Antirez on contributing dynamics] * [https://www.reddit.com/r/golang/comments/1gp833w/how_can_a_beginner_contribute_to_opensource/ Beginner questions about contributing (reddit)] * [https://medium.com/deffectivego/onboarding-issues-in-large-scale-open-source-projects-lets-talk-kubernetes-part-1-a1a64c9c9cfe Onboarding issues in large projects] * [https://opensource.guide/best-practices/ Open Source Guides: Best Practices] == Final Notes == * '''No need to reference this policy:''' If you're doing real work, your contributions will speak for themselves. * '''Support is available for genuine contributors:''' We're happy to assist contributors who show initiative and effort - this policy exists to protect that energy, not to discourage it. * '''Not sure where to start?''' Look for existing documentation pages that are unclear, outdated, or missing details, and propose a concrete improvement. * '''More contribution, more support:''' The more documentation evidence of skill and initiative you demonstrate, the more support and guidance you'll naturally receive. == Illustrative Examples == Documentation contributions that were minimal and required no prior communication: * Fix a typo or grammar issue without changing meaning * Clarify an ambiguous sentence or add a missing prerequisite * Repair a broken link or update a renamed page reference * Improve formatting for readability (headings, lists, consistent terminology) == Good First Issues == We do not have a list of good first issues. This is because after {{project age years}} years, most easy tasks have already been completed. The remaining tasks are difficult research tasks. A good and self-contained task would be to take an existing documentation page and improve clarity, structure, and accuracy. Try finding a task from our [[Reporting_Bugs#Issue_Tracker|Issue Tracker]]. * [https://forums.{{project_name_short}}/search?expanded=true&q=tags%3Astatus_open_issue_todo all status_open_issue_todo issues] Also [[Stay_Tuned|Follow {{project_name_short}} Developments]]. = See Also = * [https://forums.whonix.org/t/focus-on-low-effort-maintainability/9067 Focus on low-effort maintainability] * {{kicksecure_wiki |wikipage=Dev/maintainability |text=maintainability }} * {{kicksecure_wiki |wikipage=Stable_Version_User_Experience |text=Stable Version User Experience }} = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Development]] [[Category:MultiWiki]]