This directory contains our polished, published content. See the SuperBenefit Knowledge Base README for a general overview of the project.

Contributing Artifacts

Ready to contribute a polished piece? Follow these steps:

  1. Develop Ideas: Start in /drafts/ or /notes/, refining content with community input.
  2. Polish & Validate: Ensure content is well-structured, thoroughly reviewed, and linked to relevant sources.
  3. Move to Artifacts: Once complete and validated, move the content here.
  4. Update Metadata: Ensure all metadata fields are complete and accurate.

Maintaining Artifact Integrity

The documents in /artifacts/ represent mature, carefully reviewed knowledge. As such, they require special consideration to maintain their integrity and usefulness. Once published, these files may be linked to and relied upon by others, both within SuperBenefit and in the wider community.

  • Stable Locations: To ensure the longevity of these resources, the location and filenames of artifacts should be considered permanent. Changing a filename or directory may break existing links and disrupt users.

  • Semantic Filenames: Filenames become URL slugs, so they should be clean and semantic using this name convention file-name.md. Use lowercase, dashes as word separators, and avoid special characters.

  • Respect Authorial Intent: Artifacts often represent a significant investment of thought and effort. Changes should be made with care and respect the original author’s intention. Before making substantial edits, consult with the author and/or their team to ensure alignment.

  • Content Review and Updates: Regularly review artifacts for accuracy and relevance. If updates are needed, ensure they align with the original purpose and scope of the document.

  • Contribution Guidelines: All contributions to the knowledge base, including edits to artifacts, should follow the guidelines outlined in CONTRIBUTING.md. This includes proper formatting, clear communication, and adherence to established conventions.

  • Handling Deprecated Content: If an artifact becomes outdated or irrelevant, consider archiving it instead of deleting it. Clearly mark the artifact as “deprecated” or “archived” and provide a link to the updated or replacement resource, if available.

  • Image Optimization: Optimize images within artifacts for web use. Use appropriate file formats (e.g., .jpg, .png, .gif) and compress images to reduce file size without sacrificing quality. This improves page load times and enhances the user experience.

  • Link Verification: Regularly check for broken links within artifacts. Use a link checker tool to identify and fix any broken links to ensure that users can access all referenced resources.

  • Metadata Consistency: Ensure that metadata associated with artifacts (e.g., index, categories, authors) is consistent and accurate. This helps users find and understand the content more easily.

  • Additional Instructions: When in doubt, seek guidance from experienced contributors or SuperBenefit admins.

Support

For general support and contribution guidelines, see the SuperBenefit Knowledge Base README and CONTRIBUTING.md.