Sources of Software & Documentation: Types, Roles & Best Practices

TAKEAWAYS:

• Software sources include custom-built, off-the-shelf, open-source, and proprietary software, each with trade-offs in cost, flexibility, and support.
• Documentation is divided into system documentation (for developers) and user documentation (for end-users), both essential for maintenance and usability.
• eSewa’s API (custom-built + third-party integration) and WhatsApp’s open-source core (with proprietary layers) demonstrate hybrid software strategies.
• Poor documentation is a top cause of system failures—Nepal’s NTC’s billing system outages often trace back to undocumented updates.
• CASE tools (like Visual Paradigm) automate documentation generation, reducing errors in large projects.
• Legal compliance (licensing, copyright) is non-negotiable—Nepal’s software piracy crackdowns target unlicensed off-the-shelf tools.

1. Sources of Software: Types, Trade-offs, and Real-World Use Cases

Software can be sourced in four primary ways, each suited to different project needs. Below is a comparison table and visual breakdown:

sequenceDiagram
    participant User as Merchant
    participant eSewa as eSewa API
    participant NBR as Nepal Rastra Bank
    participant Bank as Commercial Bank
    User->>eSewa: POST /pay (₹500)
    eSewa->>NBR: GET exchange_rate
    NBR-->>eSewa: 1 NPR = 0.008 USD
    eSewa->>Bank: Deduct ₹500
    Bank-->>eSewa: Success
    eSewa-->>User: Transaction ID: TXN123
    note right of User: Custom fraud detection
    note right of eSewa: Open-source Linux backend
    note right of Bank: Proprietary banking API

classDiagram
    class SoftwareSource {
        +Name: String
        +Cost: Float
        +Flexibility: String
        +Support: String
        +Examples: String[]
    }
    class CustomBuilt {
        +Pros: Highly tailored, full control
        +Cons: Expensive, long development time
        +UseCase: "eSewa’s payment gateway (Nepal)"
    }
    class OffTheShelf {
        +Pros: Quick deployment, vendor support
        +Cons: Limited customization, licensing costs
        +UseCase: "Daraz’s inventory system (SAP)"
    }
    class OpenSource {
        +Pros: Free, community-driven
        +Cons: No official support, security risks
        +UseCase: "Linux kernel (WhatsApp servers)"
    }
    class Proprietary {
        +Pros: Enterprise-grade, SLAs
        +Cons: High cost, vendor lock-in
        +UseCase: "Ncell’s billing system (Oracle)"
    }
    SoftwareSource <|-- CustomBuilt
    SoftwareSource <|-- OffTheShelf
    SoftwareSource <|-- OpenSource
    SoftwareSource <|-- Proprietary

Key Definitions and Worked Example

• Custom-built software: Developed in-house for specific needs (e.g., a bank’s loan processing system).

  • Example: eSewa’s API integration combines custom-built payment logic with third-party APIs (e.g., NPR conversion via NBR). The custom layer handles fraud detection, while off-the-shelf APIs handle currency updates.
  • Trade-off: Costs ₹5–10 lakhs but ensures compliance with Nepal’s Fintech regulations.

• Off-the-shelf (OTS) software: Pre-built solutions (e.g., Microsoft Office, ERP systems like SAP).

  • Example: Daraz’s warehouse management uses SAP’s OTS modules for inventory tracking. Daraz customizes only the UI to match its brand.
  • Trade-off: Saves 60% development time but requires training for Nepali staff.

• Open-source software (OSS): Free to use/modify (e.g., WordPress, Linux).

  • Example: WhatsApp’s backend runs on open-source tools (Erlang/OTP) but adds proprietary layers for end-to-end encryption.
  • Trade-off: Free to deploy but requires in-house expertise to fix bugs (e.g., Nepal’s NTC uses OSS for network monitoring but struggles with local language support).

• Proprietary software: Licensed, vendor-controlled (e.g., Adobe Photoshop, Oracle databases).

  • Example: Ncell’s customer service portal uses Oracle’s proprietary CRM. Ncell pays ₹2 lakhs/year for licenses but gains 24/7 vendor support.
  • Trade-off: High upfront cost but reduces IT team workload by 40%.

How to Choose?

Use this decision matrix for your project:

Worked Example: NEPSE’s Trading System NEPSE uses a hybrid model:

• Custom-built: Core matching engine (handles high-frequency trades).
• Proprietary: Bloomberg Terminal for market data (licensed).
• Open-source: Linux servers for cost efficiency.
• Why? Custom code ensures no single vendor controls the system, while proprietary tools provide regulatory compliance.

2. Documentation: The Invisible Glue of Systems

Documentation is 50% of a system’s success. Poor docs cause:

• 30% of system failures (Gartner).
• 60% of maintenance delays (Nepal’s IT firms report).

Types of Documentation

mindmap
  root((Documentation Types))
    SystemDocs
      TechnicalSpecs
      SystemDesignDocs
      CodeComments
    UserDocs
      Manuals
      Tutorials
      FAQs
    ProjectDocs
      SRS
      TestCases
      ReleaseNotes

A. System Documentation (For Developers)

B. User Documentation (For End-Users)

Real-World Example: Pathao’s Driver App

• System Docs: Internal docs explain how the GPS routing algorithm handles Kathmandu’s traffic (uses OpenStreetMap + custom congestion models).
• User Docs: A 2-minute video shows drivers how to accept rides during peak hours (10 AM–6 PM in Nepal).
• Impact: Reduces driver support calls by 40%.

C. Project Documentation

3. Why Documentation Matters: A Case Study

Problem: Nepal’s NTC’s billing system crashes during peak hours (6–9 PM). Root Cause: Undocumented changes in the 2021 upgrade (migrated from COBOL to Java). Solution: A 3-month audit revealed:

• Missing system design docs → No one knew the new Java layer’s dependencies.
• Lack of user manuals → Staff didn’t know how to roll back. Cost: ₹5 crores in lost revenue + 2 weeks of downtime.

Lesson: Documentation isn’t optional—it’s cheaper than debugging.

4. CASE Tools: Automating Documentation

Computer-Aided Software Engineering (CASE) tools generate docs automatically. Top tools for Nepal’s market:

Example: A Nepali bank used Visual Paradigm to auto-generate 500+ UML diagrams for a new ATM system, saving 3 months of manual work.

5. Legal and Ethical Considerations

• Licensing: Off-the-shelf/proprietary software requires licenses (e.g., Microsoft’s ₹50K/year for Office 365).
  • Violation: Nepal’s IT Act 2006 imposes ₹1 lakh fines for unlicensed software.
• Open-Source Compliance: OSS like Linux requires attribution (e.g., including copyright notices).
  • Example: WhatsApp’s open-source components must credit Facebook (now Meta).
• Documentation as a Legal Shield: Courts use docs to determine liability in system failures.
  • Case: A Kathmandu hospital’s EMR system crash was traced back to undocumented database backups.

In the Real World

1. eSewa’s Hybrid Model

   • Custom-built: Fraud detection algorithm (trained on Nepali transaction patterns).
   • Off-the-shelf: Stripe API for international payments.
   • Open-source: Linux servers for cost efficiency.
   • Why? Balances compliance (Nepal’s Fintech rules) with scalability.

2. Ncell’s Billing System

   • Proprietary: Oracle database (ensures uptime for 5M subscribers).
   • System Docs: Internal "Disaster Recovery Plan" (updated quarterly).
   • Impact: System uptime improved from 95% to 99.9% after adding docs.

3. Pathao’s Driver App

   • User Docs: 1-page cheat sheet for "How to handle passenger disputes" (printed for drivers).
   • System Docs: "Traffic Route Optimization Algorithm" (explains how it avoids Kathmandu’s ring road jams).
   • Result: 30% faster ride acceptance during peak hours.

Exam Tip

1. For short-answer questions:

   • Define software sources as "custom-built, off-the-shelf, open-source, proprietary."
   • Differentiate system vs. user docs using this table:

     Aspect	System Documentation	User Documentation
     Audience	Developers, IT teams	End-users
     Purpose	Technical specs, code comments	Manuals, tutorials
     Example	"Database schema for eSewa"	"How to reset Khalti PIN"

2. For long-answer questions (10 marks):

   • Structure: Use the 5W1H format (Who, What, When, Where, Why, How).
     • Example: "Explain sources of software for a bank’s loan system."
       • What: Custom-built core system + off-the-shelf CRM (Salesforce).
       • Why: Custom for compliance; Salesforce for customer service.
       • How: Agile development with Visual Paradigm for docs.
   • Include a diagram: Draw a layered model (e.g., eSewa’s tech stack) or a mermaid sequenceDiagram of a software acquisition process.

3. Common Pitfalls:

   • ❌ Saying "open-source is always free" → False: Support/contracts cost money.
   • ❌ Ignoring legal compliance → Always mention licensing (e.g., "Nepal’s IT Act 2006").
   • ❌ Generic examples → Use Nepali companies (eSewa, Ncell, Daraz) for full marks.

4. Past Exam Patterns:

   • 2023 TU Question: "Differentiate system and user documentation with applications." Answer: Use the table above + add:
     • Application: System docs help IT teams debug; user docs reduce helpdesk calls (e.g., NTC’s IVR system).
   • 2022 PU Question: "Why do software projects fail?" Answer: Cite lack of documentation (30% of failures) + poor source selection (e.g., choosing OTS for a custom need).

Final Checklist Before Exam:

• Can you name 4 software sources and give a Nepali example for each?
• Can you draw a layered diagram of a hybrid system (e.g., eSewa)?
• Do you know one CASE tool and its use case?
• Can you explain why NTC’s system crashed using documentation gaps?

In the real world

• eSewa’s API combines custom-built fraud detection (Nepal-specific rules) with third-party APIs (NBR for currency conversion), showing how hybrid software balances compliance and efficiency. The custom layer handles local regulations (e.g., NPR thresholds), while off-the-shelf APIs reduce development time for standard tasks.
• Ncell’s Oracle CRM demonstrates proprietary software trade-offs: While the ₹2 lakh/year license ensures 24/7 vendor support, the system’s rigidity forced Ncell to hire 10 additional staff to work around Oracle’s limitations for Nepali language support.
• Nepal’s NTC uses open-source network monitoring tools (e.g., Zabbix) but faces outages when undocumented updates (e.g., server migrations) break dependencies between custom scripts and third-party plugins, proving Gartner’s statistic that poor documentation causes 30% of system failures.