[Website] Consolidating public docs contribution guidelines

[theletterf]

Currently, public documentation contribution guidelines and instructions, including docs-builder's and the style guide, are spread across repos (internal and external). This often results in their treatment as internal docs. This fragmented approach presents significant challenges for external contributors seeking to discover, understand, and adhere to the requisite standards and processes for contributing to Elastic's documentation:

• Difficulty for external contributors: External contributors may encounter obstacles in identifying the authoritative source for contribution guidelines, potentially leading to frustration and inconsistencies in their submissions.
• Inconsistent application of standards: Without a centralized repository, maintaining uniform adherence to Elastic's quality and style standards across all public contributions becomes more arduous.
• Reduced efficiency: Internal maintainers may expend excessive time directing contributors to disparate sources or rectifying issues that could have been mitigated through clearer, consolidated guidance.
• Missed opportunities: A clear, readily accessible hub has the potential to foster an increase in both the volume and quality of external contributions, thereby affirming documentation itself as a valuable product.

Content in scope

The following content is proposed for inclusion in this centralized hub:

• General contribution guidelines: A comprehensive overview of the contribution process, encompassing procedures for suggesting changes, opening pull requests, and the expected review workflow.
• Docs-builder documentation: Detailed instructions and best practices for the utilization of the docs-builder tool.
• Style guide documentation: The complete style guide for Elastic's public documentation, covering aspects such as tone, voice, grammar, formatting, and specific terminology.
• Workflow for contributions: Clear, step-by-step instructions delineating the process for contributing, from identifying areas for improvement to achieving merged changes.
• Code of conduct for contributors: Formal guidelines promoting respectful and inclusive interaction within the community.
• Licensing information: Essential details concerning the licensing requirements for contributions.
• Templates/Examples: Provision of practical templates or examples for common documentation types (e.g., new feature documentation, bug fix documentation).

Preliminary thoughts and ideas for a proposed structure or outline

We should create a dedicated section or sub-site within https://www.elastic.co/docs/extend/ with a structure similar to this:

/extend/
    ├── /contribute/  (New top-level section for all guidelines)
    │   ├── index.md (Overview: Why contribute, how to start, quick links)
    │   ├── /getting-started/ (First steps for new contributors)
    │   ├── /style-guide/
    │   ├── /docs-builder/
    │   ├── /best-practices/ (Tips for effective documentation)
    └── ... (Existing /extend/ content)

Potential risks and considerations

• Migration effort: The consolidation of existing content will require a significant effort in terms of gathering, reviewing, potentially rewriting, and republishing materials from diverse sources.
• Outdated information: Ensuring that all migrated content remains accurate and current will be an ongoing maintenance responsibility.
• Internal versus public balance: Achieving an optimal balance between providing sufficient detail for external contributors and refraining from disclosing internal processes.
• Impact on existing links: Any reorganization of existing content will require meticulous redirection management to prevent broken links.
• Audience clarity: A clear definition of the target audience (e.g., individual contributors, partners, community members) for this hub is essential to tailor content appropriately.

Metrics for success

The success of this initiative could be evaluated based on:

• Centralized source of truth: The elastic.co/docs/extend/contribute/ hub will become the undisputed, single authoritative source for all public documentation contribution guidelines, eliminating ambiguity regarding authoritative sources.
• Increased quantity and quality of contributions: Increase in the volume of public documentation contributions, coupled with an improvement in their initial quality upon submission, reducing the need for iterative revisions by internal teams.
• Reduced friction for contributors: Positive feedback from external contributors, indicating improved ease of access, comprehension, and adherence to guidelines. This can be measured through formal feedback mechanisms such as surveys.
• Improved maintainer efficiency: Documentation maintainers will allocate less time to addressing repetitive inquiries regarding contribution processes, thereby enabling greater focus on higher-value tasks.

[lcawl]

I'd love to include the contribution details for API reference content in this section too (e.g. any style guidelines or requirements that are specific to this type of content, details about how this content is handled differently than other docs, and links to the appropriate repo-specific content generation processes). This would enable any external contributor to more easily contribute to the API docs. The only aspects of this information that I can think of that would be private (i.e. not appropriate for inclusion in the public docs) would be related to APIs sourced from private repos.