Skip to content

Commit 12f9c4f

Browse files
neviaumineviaumi
committed
GH-148: Add ADR for HTML and LaTeX-based resume generation
this part of #148 Introduce an ADR documenting the decision to use HTML for visually appealing, web-based resumes and LaTeX for ATS-friendly, structured PDF outputs. Both formats pull from a single JSON source to ensure consistency and reduce duplication while fulfilling distinct user and business needs. Signed-off-by: David Ng <[email protected]>
1 parent f0a3302 commit 12f9c4f

File tree

1 file changed

+139
-0
lines changed

1 file changed

+139
-0
lines changed

‎docs/adr/20250224-html-for-readability-and-latex-for-ats-friendly-resume-output.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# HTML for Human Readability and LaTeX for ATS-Friendly Resume Output
2+
3+
- **Status**: accepted
4+
- **Deciders**: [Your Team Members] <!-- Replace with actual names -->
5+
- **Date**: [YYYY-MM-DD] <!-- Use current date -->
6+
7+
## Context and Problem Statement
8+
9+
- **Business Goal**:
10+
- Generate resumes that are highly **customizable**, **professional**, and **functional for both humans and machines** (ATS parsing).
11+
- Use **HTML** to showcase design skills and provide a web-based, human-readable resume.
12+
- Use **LaTeX** to generate structured outputs optimized for ATS compliance in PDF format.
13+
14+
- **Technical Problem**:
15+
- Resume content is already stored in a structured JSON file.
16+
- The solution should minimize duplication of effort while allowing for two separate outputs:
17+
- A **modern, styled HTML resume** for human interaction, sharing, and web hosting.
18+
- A **structured LaTeX resume** to ensure ATS parsing compatibility.
19+
- Both outputs need to stay consistent and dynamic, pulling from the same data source.
20+
21+
- **Scope**: This decision impacts the resume generation pipeline and output format generation process.
22+
23+
---
24+
25+
## Decision Drivers
26+
27+
1. Showcase **HTML/CSS/JavaScript skills** through a web-based, customizable resume design.
28+
2. Create a separate, **ATS-friendly resume** for systems that require text-heavy PDFs.
29+
3. Use **JSON** as the single source of truth for easy synchronization across both formats.
30+
4. Automate the process to minimize manual intervention and ensure consistency.
31+
32+
---
33+
34+
## Considered Options
35+
36+
1. **HTML for Human Readability + LaTeX for ATS-Friendliness.**
37+
2. **LaTeX Only** for both human-readable and ATS-friendly resumes.
38+
3. **Enhanced HTML Templates** to balance both human-readable and ATS-friendly designs.
39+
40+
---
41+
42+
## Alternatives Considered but Rejected Early
43+
44+
1. **LaTeX Only**:
45+
- **Reason eliminated**: LaTeX excels in ATS parsing but is less flexible when it comes to showcasing design skills or sharing work easily (e.g., for portfolios or web hosting).
46+
- Sharing or hosting a PDF-only resume limits interactivity and engagement with online visitors.
47+
48+
2. **Enhanced HTML Templates**:
49+
- **Reason eliminated**: Trying to balance human readability with text-heavy structures designed for ATS runs the risk of compromising flexibility and creativity.
50+
- CSS-based adjustments for ATS compliance can introduce additional complexity, requiring print-friendly CSS that might affect the overall design.
51+
52+
---
53+
54+
## Decision Outcome
55+
56+
- **Chosen Option**: **HTML for Human-Readable Resumes + LaTeX for ATS-Friendly Resumes**
57+
58+
- **Reasoning**:
59+
1. This approach uses the strengths of both formats:
60+
- **HTML**: Customizable for visually appealing, human-readable resumes that showcase design skills.
61+
- **LaTeX**: Structured and optimized for machine parsing (ATS compliance) and PDF generation.
62+
2. By using JSON as the single source of truth, both outputs remain synchronized while minimizing duplication of effort.
63+
3. HTML resumes allow for easy sharing as URLs, while LaTeX PDFs ensure maximum compatibility across ATS systems.
64+
65+
### Positive Consequences
66+
- Professional, modern HTML design highlights skills and creativity while being easy to share.
67+
- ATS parsing is ensured with LaTeX's simple, structured output.
68+
- Both formats stay in sync, with content dynamically generated from JSON.
69+
70+
### Negative Consequences
71+
- Maintaining two separate templates (HTML + LaTeX) may require some additional effort.
72+
- Familiarity with LaTeX is required for fine-tuning the ATS-focused template.
73+
74+
---
75+
76+
## Risks and Mitigations
77+
78+
- **Risk 1**: Maintaining two distinct templates could lead to inconsistencies in formatting or content.
79+
- **Mitigation**:
80+
- Use JSON as the single source of truth for all resume content.
81+
- Automate both HTML and LaTeX generation with a shared script or pipeline to ensure consistency.
82+
83+
- **Risk 2**: HTML output might not meet ATS compliance if the need arises later.
84+
- **Mitigation**:
85+
- Provide a fallback (e.g., plain-text export from JSON or a simplified LaTeX version).
86+
87+
- **Risk 3**: LaTeX requires domain knowledge for custom formatting.
88+
- **Mitigation**:
89+
- Start with pre-existing LaTeX templates like `moderncv` or `AltaCV` and only customize essentials.
90+
- Automate the LaTeX build process using tools like `pdflatex` or `tectonic`.
91+
92+
---
93+
94+
## Analysis of the Options
95+
96+
### Option 1: **HTML (Human) + LaTeX (ATS)**
97+
- **Good, because**:
98+
- HTML/CSS is highly flexible, enabling fully customized, modern designs.
99+
- LaTeX provides structured, parseable outputs for ATS and simplifies creating PDFs.
100+
- JSON as the content source ensures consistency across both human-readable and machine-readable resumes.
101+
- Both formats can be generated dynamically, minimizing duplication of effort.
102+
- **Bad, because**:
103+
- Two templates must be maintained (HTML and LaTeX), which adds complexity.
104+
105+
---
106+
107+
### Option 2: **LaTeX Only**
108+
- **Good, because**:
109+
- Tailored for ATS parsing, with minimal adjustments needed for compliance.
110+
- Outputs professional, consistent PDFs with clear structures.
111+
- **Bad, because**:
112+
- Lacks flexibility for showcasing creative or interactive designs.
113+
- Not easily shareable in digital-first forms like a web-hosted portfolio.
114+
- Requires familiarity with LaTeX for meaningful customization.
115+
116+
---
117+
118+
### Option 3: **Enhanced HTML Templates for Dual Purposes**
119+
- **Good, because**:
120+
- One template for both human-readable and ATS-friendly outputs reduces duplication.
121+
- HTML/CSS allows flexibility in design.
122+
- **Bad, because**:
123+
- Balancing creative designs with ATS compliance in pure HTML is complex and prone to errors.
124+
- Certain ATS systems that prefer PDFs might not parse HTML correctly.
125+
126+
---
127+
128+
## Final Decision
129+
130+
The decision is to adopt **HTML for human-readable resumes** and **LaTeX for ATS-friendly resumes**.
131+
132+
### Summary of the Approach
133+
134+
- Content for both templates will be dynamically generated from a structured JSON file.
135+
- **Human-readable resume** will use a flexible HTML template styled with CSS (and optionally JavaScript frameworks like React or Astro for interactivity).
136+
- **ATS-focused resume** will use a clean and structured LaTeX template to generate PDF outputs for better parsing.
137+
- Automation in the build process will generate both outputs together, ensuring consistency between the two formats.
138+
139+
This approach strikes the right balance between creativity, ease of sharing, and ATS compatibility, while leveraging structured data for scalability.

0 commit comments

Comments
 (0)