Contributing Guide

Thank you for your interest in contributing! This documentation project is community-driven: created by the community, for the community.
Our goal is to provide a clear, structured, and accessible overview of IC design flows (digital, analog, and mixed-signal) using open-source tools.

Contribution Philosophy

This documentation is not a textbook.
We keep explanations clear and concise, and for details we rely on external open-access resources.

Whenever you feel something should be explained in depth, you have three ways to do it:

1. See Also blocks ({seealso})

   • Point to related material or tutorials.
   • Example:

     ```{seealso}
     For practical examples of timing constraints, see  
     [ASIC World – RTL Design](https://asic-world.com/).

2. Inline links

   • Add links to keywords or concepts directly in the text.
   • Example:
     “Standard cells are defined in a Liberty file.”

3. Further Reading section

   • At the end of each page, include a curated list of external resources.
   • Example:

     ## Further Reading
     - [Skywater PDK Documentation](https://skywater-pdk.readthedocs.io/)  
     - [MIT OCW – Analog IC Design](https://ocw.mit.edu/courses/6-301-solid-state-circuits-fall-2003/)

Ways You Can Contribute

• Add a new concept

  • Create a new file in the proper section (concepts/, digital_flows/, analog_flows/, mixed_signal/, or tutorials/).
  • Add the new page to the main index.md through the {toctree} directive.
  • Keep explanations high-level, and use links for detailed content.

• Improve existing content

  • Add See Also, Inline links, or Further Reading to strengthen learning paths.
  • Improve explanations while keeping them short and clear.

• Fixes and clarifications

  • Correct typos, grammar, or formatting.
  • Ensure consistency in style and structure.

General Structure of a Section

Each page should follow this pattern:

1. Title (#)
2. Short Introduction — 3–5 sentences explaining the concept.
3. Subsections (if needed) — break down into smaller topics.
4. Notes / See Also — highlight key points or link to related docs.
5. Further Reading — always close with curated external resources.

Style Guidelines

• Use Markdown with MyST (.md files).
• Use clear English, simple sentences, and avoid jargon when possible.
• Prefer active voice: “This tool generates a netlist” instead of “A netlist is generated by this tool.”
• Always add a Further Reading section at the bottom of each page.

Getting Started

1. Fork the repository.
2. Create a new branch for your contribution.
3. Add or edit content in the docs/ folder.
4. Test locally:

   cd docs
   make html

   Then open _build/html/index.html in your browser.
5. Submit a Pull Request