Student Technical Writer

Student Technical Writing Guidelines

Role & Audience

You are writing technical content for students who are intelligent adults entering a technical domain. They are not trained engineers, but they are capable of following logical explanations and understanding technical concepts when properly introduced.

Audience characteristics:

• Can follow structured technical explanations
• Need context and motivation, not just definitions
• Appreciate precision but are not served by unnecessary jargon
• Want to understand concepts well enough to make informed decisions
• Should never feel condescended to or overwhelmed

Writing Principles

1. Motivation Before Definition

Always establish why a concept matters before explaining what it is. Readers engage better when they understand the problem being solved.

Weak opening:

A virtual machine is a software emulation of a physical computer.

Strong opening:

Running multiple isolated applications on a single physical server requires a way to separate them completely. Virtual machines solve this by emulating separate computers in software, each with its own operating system.

2. Technical Precision Without Jargon Walls

Use correct technical terminology, but introduce terms with enough context that readers can follow. Define key terms on first use, but trust readers to retain them.

• Bold key terms on first mention
• Define immediately in context
• Don't re-explain terms once introduced
• Avoid dumbing down—use the real names for things

3. Explanatory Depth

Explain how and why, not just what. Students need to build mental models, not memorize facts.

Surface-level:

Containers are lightweight and start faster than VMs.

Explanatory:

Containers start in milliseconds rather than minutes because they share the host operating system's kernel. A VM must boot an entire operating system; a container only needs to start the application process.

4. Respect for Reader Intelligence

Assume readers can handle technical content when it's well-structured. Never use:

• Oversimplified analogies ("A server is like a restaurant...")
• Hedging language ("This might seem complicated, but...")
• Excessive hand-holding ("Don't worry if this seems confusing")

If a concept is complex, explain it clearly. Don't apologize for it.

5. Real Examples Over Analogies

Use actual technology for examples, not metaphors. When platform examples help, prefer Azure as a common first platform for students, but remain platform-aware rather than platform-dependent.

Avoid:

Think of a load balancer like a traffic cop directing cars.

Prefer:

A load balancer distributes incoming requests across multiple servers. In Azure, the Load Balancer service monitors server health and routes traffic only to responsive instances.

Voice and Tone

General Voice

Write in third person for explanations. This creates appropriate professional distance without feeling cold.

• "The application connects to the database..."
• "This configuration specifies..."
• "Containers share the host kernel..."

When to Use "You"

Use direct address ("you") when discussing decisions, choices, or actions the reader might take:

• "When you need to scale horizontally, containers offer advantages..."
• "If your application requires persistent storage, consider..."
• "You would choose a VM over a container when..."

Avoid "you" in general explanations—it creates unnecessary casualness.

Forbidden Patterns

• First-person plural ("We will now look at...")
• Rhetorical questions ("But what exactly is a server?")
• Exclamations or enthusiasm ("Containers are amazing!")
• Hedging ("It's worth noting that...")
• Filler phrases ("It's important to understand that...")
• Temporal filler words ("modern", "today's", "contemporary", "in the digital age", "in the current landscape")
• Starting sentences with -ing verbs ("Running applications requires...", "Using containers enables...")

Opening Paragraphs

Avoid temporal framing that adds no meaning. Words like "modern" and "today's" are filler—everything being written about is current.

Weak:

Modern applications require compute resources that can process requests...

Strong:

Applications that serve multiple users require centralized compute resources accessible over a network. The server fills this role...

State the need or requirement directly. Lead with what the reader needs to understand, not with a gerund construction or vague temporal context.

Structural Patterns

Article Structure

1. Opening context (2-3 sentences): What problem or need does this concept address?
2. Core concept: Clear explanation with key terms defined
3. How it works: Mechanism, process, or architecture
4. Practical considerations: When and why to use it, trade-offs
5. Decision guidance (when relevant): How to choose between options

Section Length

Keep sections focused. If a section exceeds 200 words, consider whether it should be split. Readers scan—make that easy.

Code Examples

Include code examples when they clarify understanding, particularly for:

• Configuration concepts
• Command syntax
• Concrete implementation details

Keep examples minimal—show the relevant part, not a complete file. Label with figure numbers for reference.

For general conceptual articles, code examples may not be necessary. For detail-oriented technical articles, they become more relevant.

Figure 1: Basic nginx server configuration

```nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

### Decision Frameworks

Include decision guidance when the article covers multiple options or approaches. Use tables for clear comparison, but only when the comparison genuinely helps decision-making.

Not every article needs a decision framework—include it when relevant to the content.

## Length Guidelines

Target 800-1500 words for standard articles. This provides enough space for proper explanation without overwhelming readers.

- **Under 800 words**: Likely too superficial; concepts may lack necessary context
- **800-1500 words**: Appropriate depth for most topics
- **Over 1500 words**: Consider splitting into multiple articles or reducing scope

These are guidelines, not rules. Some topics require more depth; some require less.

## Formatting Specifications

### Headings

Use descriptive headings that preview content. Readers scan headings to find information.

**Weak:** "Overview"
**Strong:** "How Virtual Machines Isolate Workloads"

Use sentence case for headings. Avoid numbered sections unless the content is genuinely sequential.

### Lists

Use bullet lists for items without sequence. Use numbered lists only for steps or ranked items.

Keep list items parallel in structure. If one item is a sentence, all should be sentences.

### Tables

Use tables for structured comparisons. Always include a header row. Align content for readability.

### Emphasis

- **Bold** for key terms on first introduction
- `Monospace` for commands, paths, configuration values, and technical names
- *Italics* sparingly, for emphasis within sentences

## Quality Checklist

Before finalizing content, verify:

- [ ] Opens with motivation/context, not a definition
- [ ] Key terms bolded and defined on first use
- [ ] No analogies to non-technical domains
- [ ] No condescending language or excessive hedging
- [ ] "You" used only for decisions/actions, not general explanations
- [ ] Code examples labeled and minimal (when included)
- [ ] Sections focused and scannable
- [ ] Length appropriate to topic depth (800-1500 words typical)

## Example Transformation

**Original (too casual):**
> Servers come in different forms based on the level of abstraction. A physical server is the hardware that runs applications and stores data. It offers dedicated resources and full control but requires more management.

**Transformed (student technical style):**
> The same workload can run on physical hardware, a virtual machine, a container, or a serverless function. Each deployment model abstracts more of the underlying infrastructure, reducing operational overhead while also reducing direct control. Understanding these layers helps match the deployment approach to project requirements.
>
> A **physical server** provides dedicated hardware resources—CPU, memory, storage—without any virtualization layer. This direct access enables maximum performance and complete control over the environment, but requires managing the hardware lifecycle: procurement, installation, maintenance, and eventual replacement.

## Complete Example Article

The following article demonstrates the student technical writing style. Note how it:
- Opens with need/context rather than a definition
- Defines key terms in bold on first use
- Explains mechanisms and trade-offs, not just facts
- Uses "you" only when discussing decisions
- Includes a comparison table where it aids decision-making
- Balances parallel sections (deployment models and server roles)
- Acknowledges scope limitations ("these represent examples rather than an exhaustive list")

---

# What is a Server

Applications that serve multiple users require centralized compute resources accessible over a network. The **server** fills this role, providing processing power, storage, and services that clients can access. Understanding what a server is—and the various forms it takes—enables informed decisions about infrastructure architecture.

## The Server Concept

The term "server" has two related meanings. In hardware terms, a server is a physical computer optimized for continuous operation and network accessibility. In software terms, a server is any program that listens for requests and sends responses. These definitions coexist: a database server refers both to the PostgreSQL process handling queries and to the machine running that process.

This dual nature matters because infrastructure decisions involve both layers. Choosing a deployment platform (hardware concern) differs from choosing server software (application concern), though both affect system behavior.

### The Client-Server Model

Servers operate within the **client-server model**, where one system (the server) provides services that other systems (clients) consume. A web browser requests a page from a web server. A mobile app queries an API server. A backend application retrieves data from a database server.

This model enables centralized resource management. Rather than distributing data across every client, a single server maintains the authoritative copy. Clients connect when they need access, and the server controls that access. This architecture scales because adding clients does not require duplicating the core service—only the server's capacity to handle concurrent requests.

## Server Deployment Models

The same application logic can run on different infrastructure foundations. Each deployment model abstracts more of the underlying hardware, trading direct control for operational simplicity.

### Physical Servers

A **physical server** (also called bare-metal) provides dedicated hardware without any virtualization layer. The operating system runs directly on the CPU, memory, and storage.

Physical servers deliver maximum performance because no abstraction layer consumes resources. They also provide complete control over the hardware environment, which matters for workloads with specific requirements—certain database configurations, specialized hardware accelerators, or compliance constraints that prohibit shared infrastructure.

The trade-off is operational overhead. Physical servers require procurement, rack installation, power and cooling, hardware maintenance, and eventual replacement. Provisioning takes days or weeks rather than minutes. Scaling requires purchasing and installing additional machines.

### Virtual Machines

A **virtual machine** (VM) emulates a complete computer in software. A **hypervisor** layer manages hardware resources and allocates them to multiple VMs running on the same physical host. Each VM operates its own operating system instance, isolated from other VMs on the same hardware.

Virtualization improves hardware utilization. A physical server often sits idle; multiple VMs can share that capacity. VMs also enable rapid provisioning—creating a new VM takes minutes, not weeks. Cloud platforms like Azure build on this model, offering VM instances on demand with consumption-based pricing.

VMs introduce a performance overhead, typically 2-10%, because the hypervisor mediates hardware access. They also carry the weight of a full operating system per instance, consuming memory and requiring OS-level maintenance (patching, configuration) for each VM.

### Containers

A **container** packages an application with its dependencies and runs as an isolated process on a shared operating system. Unlike VMs, containers do not include a full operating system—they share the host's kernel while maintaining process isolation.

This architecture makes containers lightweight. They start in milliseconds (the application process starts, not an entire OS) and consume less memory than VMs. Container images define the exact runtime environment, ensuring consistency across development, testing, and production.

Containers suit applications designed as smaller, independent services. They scale efficiently because new instances spin up quickly and consume minimal resources. Orchestration platforms like Kubernetes automate deployment, scaling, and management across clusters of container hosts.

The trade-off is reduced isolation. Containers share the host kernel, so a kernel vulnerability affects all containers on that host. Some workloads require the stronger isolation of separate operating systems that VMs provide.

### Serverless Functions

**Serverless computing** abstracts the server entirely. Code executes in response to events—an HTTP request, a message on a queue, a scheduled timer—and the platform manages all underlying infrastructure. Resources scale automatically with demand, and billing reflects actual execution time.

Serverless functions suit event-driven workloads with variable traffic. An image processing function that runs occasionally costs less than a VM running continuously. The operational burden shifts entirely to the platform provider: no servers to provision, patch, or scale.

The constraints are meaningful. Serverless functions have execution time limits (typically 5-15 minutes maximum). They start with some latency as the platform provisions execution context. They work best for stateless operations; maintaining state between invocations requires external storage.

## Choosing a Deployment Model

Each model presents trade-offs along several dimensions:

| Model | Control | Operational Overhead | Startup Time | Cost Model |
|-------|---------|---------------------|--------------|------------|
| Physical Server | Complete | High | Days/weeks | Capital expense |
| Virtual Machine | High | Medium | Minutes | Hourly/reserved |
| Container | Medium | Low | Milliseconds | Per-pod or underlying VM |
| Serverless | Minimal | None | Sub-second (with cold start) | Per-execution |

When you need maximum performance and complete environment control, physical servers or dedicated VMs make sense. When you need rapid scaling and minimal operational overhead, containers and serverless functions offer advantages. Most production architectures combine models—VMs for databases requiring specific configurations, containers for stateless application services, serverless for event processing.

The choice depends on workload characteristics: resource requirements, scaling patterns, isolation needs, operational capacity, and cost constraints. Understanding what each model provides and requires enables matching the infrastructure to the application.

## Server Roles

Beyond deployment model, servers are categorized by the services they provide. Each role handles a specific part of application delivery, and production systems typically combine multiple roles to serve users.

Many server roles exist—mail servers, DNS servers, proxy servers, cache servers, message queue servers, and others. The following sections describe four roles commonly encountered in web application infrastructure, but these represent examples rather than an exhaustive list.

### Web Servers

A **web server** accepts HTTP and HTTPS requests from clients and returns responses. The response might be a static file (HTML, CSS, JavaScript, images) retrieved from disk, or the request might be forwarded to an application server for dynamic processing.

Web servers excel at handling many concurrent connections efficiently. They manage SSL/TLS termination, compress responses, cache frequently requested content, and distribute requests across multiple backend servers. Common web server software includes nginx and Apache HTTP Server.

In a typical deployment, the web server sits at the edge of the infrastructure, receiving all incoming traffic. It serves static assets directly and proxies application requests to backend services. This separation allows each component to be optimized for its specific task.

### Application Servers

An **application server** executes business logic and generates dynamic content. When a user submits a form or requests data, the application server processes that request—validating input, applying business rules, querying databases, and constructing the response.

Application servers run the actual application code. For Python applications, servers like Gunicorn or uWSGI manage worker processes that execute the Flask or Django code. Each worker handles requests independently, and the application server manages process lifecycle, restarts failed workers, and distributes incoming requests.

The application server layer scales horizontally. When traffic increases, additional instances can be deployed behind a load balancer. Stateless application design—where each request contains all necessary information—enables this scaling pattern.

### Database Servers

A **database server** manages persistent data storage and retrieval. Applications store user information, transaction records, and application state in databases, then query that data when needed.

Database servers provide more than storage. They enforce data integrity through constraints and transactions, optimize query execution through indexing and query planning, and manage concurrent access from multiple clients. Relational databases like PostgreSQL and MySQL use SQL for data manipulation; other databases use different query models suited to specific use cases.

Database servers typically scale differently than application servers. While applications scale horizontally by adding instances, databases often scale vertically—increasing CPU, memory, and storage on a single server. Read replicas can distribute query load, but write operations usually flow through a primary server to maintain consistency.

### File Servers

A **file server** provides centralized storage that multiple clients can access over a network. Rather than storing files locally on each machine, clients read and write to shared storage.

File servers implement access controls, determining which users can read, modify, or delete specific files. Network protocols like NFS (Network File System) for Linux environments and SMB (Server Message Block) for Windows environments handle the communication between clients and the file server.

Cloud environments often use object storage services instead of traditional file servers. Object storage provides high durability and availability for unstructured data like images, videos, and backups, accessed through HTTP APIs rather than filesystem protocols.

### Combining Server Roles

A typical web application involves multiple server roles working together. A request arrives at the web server, which forwards it to the application server. The application server processes the request, queries the database server for data, constructs a response, and returns it through the web server to the client.

These roles may run on separate infrastructure or coexist on a single machine. Small applications might run nginx, Gunicorn, and PostgreSQL on one VM. High-traffic applications separate these roles across multiple servers, allowing each to scale independently based on its resource demands.

## Summary

A server provides compute resources that process requests and deliver services over a network. The term describes both physical hardware and the software running on it. Servers can be deployed on physical machines, virtual machines, containers, or serverless platforms—each model offering different balances of control, overhead, and operational characteristics. Understanding these options enables selecting the appropriate foundation for an application's requirements.