Document Version Control & Technical Writing Tools

TAKEAWAYS:

• Version control tracks changes in documents collaboratively, preventing conflicts and enabling rollback to earlier states.
• Git is the industry-standard tool for version control, used by developers worldwide (including Nepali startups like Pathao for code/documentation).
• Markdown and LaTeX simplify formatting for technical manuals, while Google Docs offers real-time collaboration for teams.
• Document lifecycle management includes stages like drafting, reviewing, approving, and archiving—critical for compliance in sectors like banking (NMB, Nabil).
• Tools like Confluence or Notion integrate version control with wikis, used by NTC for infrastructure documentation.
• Ethical tool use requires proper attribution (e.g., citing open-source licenses in software docs).

---

Core Concepts

1. What is Document Version Control?

Document version control is a systematic method to track changes, revisions, and iterations of a document over time. It ensures:

• Collaboration: Multiple authors can work simultaneously without overwriting each other’s work.
• Traceability: Every change is logged with a timestamp, author, and reason (e.g., "Fixed typo in API documentation").
• Recovery: Previous versions can be restored if errors are introduced (e.g., reverting to a stable draft before a product launch).
• Compliance: Critical in regulated industries (e.g., NEPSE’s financial reports must track all revisions for audits).

How It Works:

1. Baseline: The original or approved version of the document.
2. Check-in/Check-out: Authors "lock" a document to edit (check-out) and "save" changes (check-in) to update the version.
3. Branching: Creating parallel versions (e.g., a "dev" branch for experimental changes vs. a "stable" branch for production docs).
4. Merging: Combining changes from branches (e.g., merging feedback from a Khalti team into the main project wiki).
5. Diff Tools: Highlighting differences between versions (e.g., comparing two drafts of a Daraz return policy).

---

2. Parts of Version Control Systems

---

3. Why Version Control Matters in Technical Writing

Technical documents (manuals, APIs, policies) are living artifacts that evolve. Without version control:

• Chaos: Multiple authors edit the same file, leading to conflicts (e.g., two Daraz team members updating the same shipping policy simultaneously).
• Loss of History: Critical changes (e.g., a NEPSE rule update) are lost if only the latest file is saved.
• Non-Compliance: Industries like healthcare or finance require audit trails (e.g., CIAA documents must track all revisions).

Real-World Analogy: Think of version control like Khalti’s transaction logs:

• Every payment has a unique ID, timestamp, and status (success/failure).
• If a dispute arises, you can trace back to the exact transaction (like reverting to a previous doc version).

---

Key Tools for Version Control and Technical Writing

A. Version Control Tools

How Git Works (Simplified):

1. Initialize: Create a repository (git init).
2. Stage Changes: Add files to be tracked (git add manual.md).
3. Commit: Save changes with a message (git commit -m "Updated API docs").
4. Push/Pull: Sync with a remote server (e.g., GitHub).
5. Branch: Create a new line of work (git branch feature/new-ui).
6. Merge: Combine branches (git merge feature/new-ui).

Worked Example: Fixing a Bug in eSewa’s User Guide

• Problem: A user reports confusion in the "Payment Reversal" section.
• Process:
  1. A writer clones the repo (git clone https://github.com/eSewa/docs).
  2. Creates a branch (git checkout -b fix/reversal-section).
  3. Edits the Markdown file locally, then stages/commits:

     git add user_guide.md
     git commit -m "Clarified reversal steps with screenshots"
     

  4. Pushes to GitHub and opens a pull request for review.
  5. After approval, merges into main (git merge fix/reversal-section).

---

B. Technical Writing Tools

Markdown Example (for API Documentation):

# eSewa Payment API
**Version**: 2.1
**Last Updated**: 2023-10-15

## Endpoint: `/payments/reverse`
**Description**: Initiates a payment reversal.
**Request**:
```json
{
  "transaction_id": "txn_12345",
  "reason": "Duplicate payment"
}

Response:

{
  "status": "success",
  "reversal_id": "rev_67890"
}

Note: Requires admin privileges. See Auth Guide.

---

In the Real World

1. eSewa’s Documentation Workflow:

   • Tool: Git + Markdown.
   • How: The team maintains a public GitHub repo for API docs. Every change (e.g., adding a new endpoint) is committed with a clear message like "Added /payments/split feature".
   • Why: Ensures transparency for developers and allows users to track when features were added (e.g., "Split payments launched in v2.3").

2. Ncell’s Network Manuals:

   • Tool: Confluence + SVN.
   • How: Engineers edit the latest version of the 4G Network Deployment Guide in Confluence, which automatically logs changes. Older versions are archived in SVN for compliance.
   • Why: If a network outage occurs, Ncell can revert to the manual used during the last stable deployment.

3. Pathao’s Driver App Updates:

   • Tool: GitHub + Pull Requests.
   • How: When Pathao adds a new feature (e.g., "Electric Vehicle Mode"), the product team:
     1. Creates a branch for the new feature.
     2. Updates the driver guide in Markdown.
     3. Submits a PR for review by the compliance team.
     4. Merges only after testing.
   • Why: Prevents broken guides from being published to drivers.

4. NEPSE’s Regulatory Documents:

   • Tool: Microsoft Word (Track Changes) + Shared Drive.
   • How: When NEPSE updates listing rules, the legal team:
     • Enables "Track Changes" in Word.
     • Edits the document and adds comments (e.g., "Clarify clause 5.2").
     • Saves as Listing_Rules_v3.1_with_changes.docx.
     • Final version is approved and saved as Listing_Rules_v3.1_final.pdf.
   • Why: Audit trails are required for regulatory filings.

---

Collaboration Scenarios

Scenario 1: Daraz’s Shipping Policy Update

Team: Logistics (2 members), Legal (1), Customer Support (1). Tool: Google Docs + Git for backup. Process:

1. Logistics drafts changes in Google Docs (version history enabled).
2. Legal reviews and suggests edits via comments.
3. Support tests the updated policy with real orders.
4. Final version is exported to PDF and committed to Git:

   git add shipping_policy_v2.md
   git commit -m "Updated for holiday shipping deadlines"
   git push origin main
   

Potential Conflict:

• If two team members edit the same section simultaneously, Google Docs’ real-time cursor tracking shows conflicts. The latest changes are manually resolved.

Scenario 2: NTC’s Fiber-Optic Manual

Tool: MadCap Flare + SVN. Process:

1. A technician writes a new section on "Fiber Splicing" in Flare.
2. Flare auto-generates a PDF and HTML version.
3. The manual is checked into SVN with a tag fiber_manual_v1.2.
4. If a typo is found, the team:
   • Checks out the latest version from SVN.
   • Edits in Flare.
   • Commits as fiber_manual_v1.2.1_fix.

Advantage: Single-sourcing ensures the same content appears in both the PDF and online help system.

---

Best Practices for Version Control

1. Use Descriptive Commit Messages:

   • ❌ Fixed bug (vague).
   • ✅ Updated API timeout error message to match new backend response format (clear).

2. Branch Strategically:

   • feature/ for new additions (e.g., feature/multi-language-support).
   • bugfix/ for patches (e.g., bugfix/payment-failure-loop).

3. Regularly Merge:

   • Avoid "merge hell" by integrating changes weekly (e.g., Khalti merges PRs every Friday).

4. Backup Remotely:

   • Use GitHub/GitLab for cloud backups (e.g., Ncell’s docs are mirrored on-premise and in GitLab).

5. Document the Process:

   • Include a CONTRIBUTING.md file in your repo explaining how to submit changes (e.g., OpenNTT’s guide for contributors).

---

Common Pitfalls and How to Avoid Them

---

Exam Tip

This unit is highly practical and often tested with:

1. Short Notes:

   • Define version control, branching, or Git workflows.
   • Example answer for "What is document version control?":

     Document version control is a system to manage changes to documents over time, ensuring traceability, collaboration, and recovery of previous states. It uses tools like Git or SVN to track edits, authors, and timestamps (e.g., NEPSE tracks revisions of listing rules for compliance).

2. Scenario-Based Questions:

   • "How would you handle a conflict if two writers edit the same section of a manual for NTC?"

     Use a tool like Google Docs with real-time collaboration or Git with branching. In Google Docs, resolve conflicts by comparing changes side-by-side. In Git, pull the latest changes, resolve conflicts locally, then commit.

3. Tool Comparisons:

   • Compare Git vs. Google Docs for version control:

     Feature	Git	Google Docs
     Best For	Code/docs with complex branching	Real-time collaborative editing
     Conflict Handling	Manual merge resolution	Auto-highlights conflicting edits
     Offline Use	Yes (with Git CLI)	No (requires internet)
     Nepali Use Case	Pathao’s code/docs	Khalti’s press releases

4. Worked Examples:

   • "Show how you’d use Git to track changes in a user manual for eSewa."

     1. Initialize repo: git init eSewa_manual.
     2. Add initial manual: git add user_guide.md.
     3. Commit first version: git commit -m "Initial draft".
     4. Create branch for updates: git branch -b fix/onboarding.
     5. Edit and commit: git add user_guide.md; git commit -m "Added screenshot steps".
     6. Merge back: git checkout main; git merge fix/onboarding.

5. Ethical Considerations:

   • "Why is proper version control ethical in technical writing?"

     It ensures transparency (e.g., NEPSE can prove no unauthorized changes were made to rules) and accountability (every edit is attributed to an author). Poor version control can lead to fraud or misinformation.

---

Sample Exam Questions and Answers

Question 1:

"Explain the stages of document version control with an example from a Nepali company like Ncell."

Answer: Document version control involves these stages:

1. Baseline: The original document (e.g., Ncell’s 4G Network Deployment Guide v1.0).
2. Check-out: A technician edits the guide locally (e.g., adds a section on "5G Readiness").
3. Edit: Changes are made in a tool like Confluence or Word.
4. Check-in: The updated guide is saved back to the repository with a commit message:

   git add deployment_guide.md
   git commit -m "Added 5G compatibility checklist"
   

5. Review: A peer reviews changes via GitHub PR or Confluence comments.
6. Merge: Approved changes are merged into the main branch (e.g., git merge feature/5g-updates).
7. Tag: A stable version is tagged (e.g., v1.1) for archiving.

Ncell Example: When Ncell rolled out 5G in Kathmandu, the team:

• Branched the guide to avoid disrupting the stable v1.0.
• Merged only after testing the new section with field technicians.
• Tagged the final version as 5G_Deployment_v1.1 for compliance audits.

---

Question 2:

"How would you use Markdown to document an API for a Nepali fintech app like Khalti? Provide a sample and explain its advantages."

Answer: Sample Markdown for Khalti’s /transfer API:

# Khalti Payment Transfer API
**Endpoint**: `POST /api/v2/transfer`
**Auth Required**: `Bearer <access_token>`
**Request Body**:
```json
{
  "amount": 500,
  "from_account": "KH001",
  "to_account": "KH002",
  "reference": "Salary Oct 2023"
}

Responses:

• Success (200):

  { "status": "completed", "transaction_id": "txn_98765" }
  

• Error (402):

  { "error": "Insufficient balance", "code": "INSUFF_FUNDS" }
  

Notes:

• Rates are subject to Khalti’s fee schedule.
• See Webhook Docs for real-time notifications.

Advantages of Markdown for Khalti:

1. Readability: Plain-text format is easy to read in code editors or GitHub.
2. Version Control: Markdown files integrate seamlessly with Git (e.g., Khalti’s API docs are versioned in GitHub).
3. Export Flexibility: Can be converted to PDF (for internal use) or HTML (for the developer portal).
4. Collaboration: Multiple engineers can edit the same file in VS Code with Git integration.
5. Lightweight: No complex formatting—ideal for APIs where clarity > design.

---

Question 3:

"Compare the advantages and disadvantages of using Git vs. Google Docs for version control in a technical writing project for NTC."

Recommendation for NTC:

• Use Git for technical documents (e.g., SDH Installation Manual) where branching and code integration are needed.
• Use Google Docs for collaborative drafting (e.g., Annual Report) with non-technical stakeholders.

---

Final Checklist for Students

Before the exam, ensure you can:

1. Define version control, branching, merging, and commit.
2. Explain how Git or Google Docs would be used in a Nepali tech company (e.g., Pathao, Ncell).
3. Write a Markdown or LaTeX snippet for a technical document (e.g., API, manual).
4. Describe the stages of version control with a real-world example.
5. Compare two tools (e.g., Git vs. Confluence) for a specific use case.
6. Identify ethical issues in version control (e.g., unauthorized deletions, lack of attribution).