LFX Mentorship - Liboqs

[SHISKEBAB]

Improving Documentation and Onboarding for liboqs

Name: Shishir Shreedhar Tambe
GitHub: SHISKEBAB
Email: shishirstambe01@gmail.com
Mentorship Period: 8 Weeks
Mentor:@bhess

---

Background and Motivation

As a technical writer, I’ve long been fascinated by the intersection of cutting-edge cryptography and open-source software. The liboqs library stands out for its real-world relevance in post-quantum cryptography, its alignment with emerging standards, and its integration into widely-used protocols like TLS.

I’ve spent time exploring the repository and familiarizing myself with its structure and existing documentation. While I haven’t contributed or built the project yet, my audit helped me identify several opportunities to improve clarity, onboarding, and contributor guidance. With a strong foundation in technical communication, my goal is to help make liboqs more accessible—both to new developers and the broader cryptographic community—through structured, easy-to-navigate, and sustainable documentation.

What excites me most is the chance to support a critical low-level system like liboqs by bridging the gap between complex engineering and clear communication. I believe good documentation is infrastructure—and I’m excited to contribute to it.

I’ve also applied for this mentorship via the LFX platform, and wanted to take this opportunity to introduce myself to the team and community I hope to collaborate with.

---

Project Overview

The goal of my contribution is to enhance liboqs’s documentation to support onboarding, contributor engagement, and long-term maintainability. Key focus areas will include:

• Clarifying installation and usage instructions.
• Developing clear contributor guides with visuals and examples.
• Improving inline code comments and technical explanations.
• Proposing a more structured documentation layout (information architecture).
• Exploring tools like MkDocs, Sphinx, or Docusaurus for publishing clean, browsable docs.

---

Deliverables

By the end of the 8-week mentorship, I aim to deliver:

• Contributor onboarding materials and setup guides.
• Enhanced usage documentation with sample workflows.
• API or code-level documentation (generated via Sphinx or similar tools).
• Step-by-step tutorials or example use cases.
• A proposal or implementation for a documentation publishing workflow (e.g., GitHub Pages or Read the Docs).
• A final mentorship report and documentation walkthrough.

---

Timeline (8 Weeks)

Week 1 — Familiarization & Setup

• Understand project architecture and developer workflows.
• Identify and map current documentation coverage.
• Set up development environment.

Week 2 — Audit & Gap Analysis

• Perform a detailed content audit.
• Propose improvements in structure, tone, and clarity.
• Identify audience segments (users, devs, contributors).

Week 3 — Contributor Docs

• Draft onboarding and setup guides.
• Add visuals or diagrams to aid understanding.
• Cover GitHub workflows, CI steps, etc.

Week 4 — Usage & Installation Guide

• Improve installation instructions.
• Add tested, reproducible usage examples.

Week 5 — API & Code-Level Documentation

• Collaborate with developers to document modules and APIs.
• Use tools like Sphinx to auto-generate docs if applicable.

Week 6 — Tutorials & Examples

• Create hands-on walkthroughs or use-case-driven examples.
• Gather feedback and refine content.

Week 7 — Polish & Collaborate

• Review all docs for tone, consistency, and formatting.
• Collaborate with devs to test and verify tutorials.
• Apply final edits and revisions.

Week 8 — Final Review & Wrap-up

• Finalize documentation hub (e.g., MkDocs or GitHub Pages).
• Submit PRs and summary report.
• Optional: host a brief walkthrough for contributors.

---

Tools, Languages, and Skills

• Writing & Formatting: Markdown, reStructuredText
• Version Control: Git, GitHub
• Documentation Tools: MkDocs, Sphinx, GitHub Actions
• Editor: VS Code
• Visuals: Snagit (for screenshots and guides)
  I’m also interested in exploring documentation deployment workflows, automated site builds, and modular content reuse.

---

Prior Work and Initiative

• Explored the structure and layout of the liboqs repo.
• Identified several areas for improvement in clarity and accessibility.
• Haven’t submitted code yet, but plan to begin contributing with documentation improvements and small PRs.

Looking forward to any feedback, guidance, or suggestions on how I can best contribute. I’m excited to be part of this journey and collaborate with the liboqs team and community!

Thanks!
— Shishir