██FR█████ █INTELL███████████

Why Ignoring Documentation Can Set Back Junior Developers’ Careers?


This content originally appeared on DEV Community and was authored by Saim Ahmed

Why Most Junior Devs Skip Documentation

Most junior devs skip documentation because they think it’s a waste of time. But this is actually their biggest blunder—it’s often the root cause of chaos and failed project ideas.

Before building a project, if you don’t know what you’re building and why, there’s a high chance you’ll end up building features you don’t need. At a small scale, this might be tolerable, but at a larger scale, it creates massive chaos. You end up fixing bugs in features that were unnecessary or even useless.

Image-of-advantages-and-disadvantages-of-documentation

My Experience

I was building an authentication system. I built the frontend and backend, but all of it was done without planning. Every single day, I discovered things that should have been defined at the start. I kept adding new fields to my MongoDB schemas and, after building controllers, I realized I had missed many validator middlewares and other essentials. I felt like I was building a house and discovering halfway that I forgot to design the doors. Every day something broke.

What was you experience when you started working on project without documentation?

The Solution

You’re probably curious how I solved this problem. I’m a 5th-semester BS Software Engineering student. Back in my 3rd semester, I studied the Software Requirement Specification (SRS) document, which covers Functional Requirements, Non-Functional Requirements, etc. At that time, I hadn’t built a real system, so it was all theoretical.

Now that I was building a real system, I started writing an SRS document for my authentication system. I researched and defined everything in detail, including:

  • OAuth implementation

  • Compliance requirements like GDPR

  • Additional controllers, e.g., “Revoke All Sessions”

  • Telemetry to track user device information like IP, location, etc.

Software Requirements Specification (SRS) — Authentication System

1. Purpose

The authentication system will let users register, log in, and prove their identity securely before accessing any application.

It should be secure, scalable, and flexible — capable of growing into an enterprise-grade Identity & Access Management (IAM) system, including multi-factor authentication, OAuth federation, SSO, and advanced monitoring.

2. Scope

2.1 In-Scope (MVP)

The authentication system must support the following functionality in its minimum viable product (MVP):

  • User registration using email, phone number, or third-party OAuth providers.

  • Email verification before account activation.

  • Login and logout capabilities.

  • Password reset and password change.

  • Session management, including refresh and revoke functionality.

  • Basic user roles (Admin, User).

2.2 Out-of-Scope for MVP (Planned for Future/Enterprise Readiness)

The following features are not required for the MVP but may be introduced in later enterprise-grade versions:

  • authentication mechanisms.

  • Automated user provisioning and management (e.g., via SCIM).

  • Advanced audit logging and monitoring dashboards.

  • Risk assessment with anomaly detection.

  • Telemetry dashboards for system and authentication monitoring.

  • Real-time alerting and notification capabilities.

  • Multi-Factor Authentication (MFA) methods (e.g., authenticator apps, SMS, hardware keys, backup codes).

  • Federation using OAuth 2.1 / OpenID Connect with additional providers (e.g., GitHub, LinkedIn).

  • Passwordless authentication (e.g., WebAuthn, magic links).

  • Single Sign-On (SSO) using standards such as SAML.

  • Risk-based

3. Users

The system will be used by the following user groups:

  • End Users: Register, verify their accounts, log in, and manage personal profile details.

  • Administrators: Manage user accounts, roles, and permissions.

  • Developers: Consume and integrate authentication APIs with client applications.

4. Definitions, Acronyms, Abbreviations

  • MFA — Multi-Factor Authentication.

  • RBAC — Role-Based Access Control.

  • ABAC — Attribute-Based Access Control.

  • JWT — JSON Web Token.

  • SSO — Single Sign-On.

  • OAuth — Open Authorization (standard for delegated access).

  • OpenID Connect — Authentication layer on top of OAuth 2.1.

  • GDPR — General Data Protection Regulation.

5. Functional Requirements

5.1 Authentication Core

  • Users must be able to register using email, phone number, or supported third-party identity providers.

  • Users must be able to log in with credentials (email/phone + password) or through supported third-party identity providers.

  • Users must be able to log out.

  • The system must allow issuing new access tokens without requiring re-login.

  • The system must prevent users from reusing a configurable number of their most recent passwords.

5.2 Password & Credentials Management

  • Users must be able to request a password reset link or code.

  • Users must be able to reset their password using the provided link/code.

  • Users must be able to change their password while logged in.

  • Users must be able to update account credentials (email, username, or phone number).

5.3 Verification & Identity

  • Users must be able to verify their email via link or code.

  • Users must be able to verify their phone via one-time code.

  • Users must be able to request resending of verification links/codes.

  • The system must support multi-factor authentication (e.g., authenticator apps, backup codes).

5.4 User & Session Management

  • Users must be able to view, update, and delete profile details.

  • Users must be able to view active sessions, revoke all sessions, or revoke sessions individually.

  • Users must be able to deactivate or delete their account.

5.5 Authorization & Roles

  • The system must allow creating, reading, updating, and deleting roles (e.g., Admin, User).

5.6 Federation

  • Users must be able to authenticate through third-party identity providers.

5.7 Security & Monitoring

  • The system must record all critical security events (e.g., logins, failed logins, password changes, MFA challenges, account deactivation, admin actions).

  • The system must detect suspicious behavior (e.g., abnormal login patterns, device mismatches, repeated failures).

  • The system must temporarily or permanently block accounts, IPs, or devices exhibiting suspicious activity.

  • The system must enforce configurable rate limits to prevent brute force or denial-of-service attacks.

5.8 Telemetry & Observability

  • The system must collect telemetry for:

    • Authentication events (e.g., login success/failure, logout, token refresh).
    • Security events (e.g., suspicious login, password reset, MFA challenges).
    • System health metrics (e.g., response times, error rates, latency).

  • The system must expose telemetry in industry-standard formats.

  • The system must support integration with external alerting systems for both threshold-based and anomaly-based alerts.

6. Non-Functional Requirements

6.1 Security

  • The system shall securely hash all user passwords using a strong one-way algorithm (e.g., Argon2 or bcrypt).

  • The system shall ensure all API endpoints are served exclusively over HTTPS.

  • The system shall implement rate limiting to mitigate brute force login attempts.

  • The system shall maintain continuous audit logging of authentication and authorization events.

  • The system shall support Multi-Factor Authentication (MFA) in future releases.

6.2 Scalability

  • The system shall support scaling from hundreds to millions of concurrent users without service degradation.

  • The system shall implement stateless token handling (e.g., JWT or opaque tokens with introspection).

  • The system shall support session storage in distributed caching systems (e.g., Redis, DynamoDB).

6.3 Performance

  • Login request must complete within 200ms under normal load.

  • System must support 10,000 concurrent logins.

  • Token refresh latency ≤ 100ms.

6.4 Availability

  • The system shall achieve a minimum uptime of 99.9%.

    The system shall ensure session refresh and logout functionality remain consistent across distributed environments.

7. Data Model (Basic)

User

  • id (PK)

  • email

  • name

  • phone

  • password_hash

  • email_verified (boolean)

  • phone_verified (boolean)

  • role (enum: Admin, User, etc.)

  • mfa_enabled (boolean)

  • created_at

  • last_login

  • failed_attempts

  • status (active, locked, deactivated, deleted)

Session/Token

  • token_id (PK)

  • user_id (FK → User.id)

  • issued_at

  • expires_at

  • revoked (boolean)

  • ip_address

  • device_info

  • refresh_token_id (nullable, for refresh flows)

Audit Log

  • log_id (PK)

  • user_id (FK → User.id, nullable for system-level events)

  • event_type (login_success, login_failure, password_change, MFA_challenge, etc.)

  • ip_address

  • device_info

  • timestamp

MFA_Credential

  • mfa_id (PK)

  • user_id (FK → User.id)

  • type (TOTP, SMS, Email, SecurityKey, BackupCode)

  • secret_hash (for TOTP or backup codes)

  • created_at

  • last_used_at

  • is_active (boolean)

OAuth_Provider

  • provider_id (PK)

  • user_id (FK → User.id)

  • provider_name (Google, GitHub, Facebook, LinkedIn)

  • provider_user_id (unique per provider)

  • access_token (optional, if stored)

  • refresh_token (optional, if stored)

  • linked_at

Role

  • role_id (PK)

  • name (Admin, User, Moderator, etc.)

  • description

Permission

  • permission_id (PK)

  • name (e.g., manage_users, view_logs, update_roles)

  • description

Role_Permission (Mapping table)

  • role_id (FK → Role.role_id)

  • permission_id (FK → Permission.permission_id)

Telemetry_Event

  • telemetry_id (PK)

  • type (auth_event, security_event, system_health)

  • details (JSON for structured event data)

  • created_at

8. Data Requirements

  • Passwords are never stored in plain text.

  • Audit logs retained for 90 days minimum.

  • Sessions expire after 15 minutes of inactivity.

  • Refresh tokens valid for 7 days, revocable at any time.

  • Personally Identifiable Information (PII) must be encrypted at rest (AES-256).

9. Risks & Assumptions

  • Weak/reused passwords → enforce policy + MFA later.

  • Email/phone compromise → mitigate with MFA.

  • Risk of DDoS → mitigate with rate limiting & IP bans.

  • Scaling requires distributed session/token store.

10. Success Criteria

  • Users can register, verify identity, and log in.

  • Users can reset/change credentials securely.

  • Admins can manage accounts & roles.

  • Audit logs capture all critical actions.

  • Suspicious activity is logged and flagged.

Need your advice !

image-of-need-guidance

I’m looking for advice from senior developers on what I should include or remove in my documentation. Additionally, would you recommend creating separate documents for software design and architecture, including architectural diagrams? If you have written any documentation can you share it here ?

if you have any question about this artice please ask in the comment

Follow me

hashnode : https://hashnode.com/@saim152


This content originally appeared on DEV Community and was authored by Saim Ahmed