PUBLIC HEALTH AND REGULATORY PHARMACY

Institute of Pharmacy S.Y. 2025-2026

4th Year I 1st Sem Internship

○​ "This" could mean config files or dynamic

TECHNICAL WRITING 1 imports. Fix: "Dynamic imports may be a
security risk."
WORDS AND CLARITY
1. Define Unfamiliar Terms Retention Boosters
●​ Actionable: ●​ Quiz Questions:
●​ Link to existing explanations for known terms. ●​ When should you define an acronym?
●​ Define new terms in-line or in a glossary.
○​ Answer: At first use, if it’s shorter and used
●​ Example:
frequently.
○​ "The Flux Capacitor (a time-travel device)
powers the DeLorean." ○​ Fix: "The API connects to the database. It is
slow."
2. Consistent Terminology ○​ Answer: "The API connects to the database.
●​ Principle: Renaming terms confuses readers (like The API is slow."
variable renaming in code). ●​ Mnemonic: "D.A.R.T." for clarity:
●​ Actionable: ○​ Define terms
●​ Stick to one term (e.g., "Protocol Buffers" or ○​ Avoid renaming
"protobufs," not both). ○​ Restrict pronouns
●​ Introduce shortcuts early: "Protocol Buffers ○​ Tame acronyms
(protobufs)..." then use "protobufs."
●​ Mnemonic: "One Term, One Meaning" (OTOM). ACTIVE VS PASSIVE VOICE
1. Active vs. Passive Voice: The Basics
3. Acronym Rules
●​ Active Voice: Actor + Verb + Target (clear and direct).
●​ Guidelines: Define acronyms at first use: "Telekinetic
○​ Example: "The cat (actor) sat (verb) on the
Tactile Network (TTN)...".
mat (target)."
●​ Bold both full term and acronym initially.
●​ Passive Voice: Target + Verb + Actor (indirect, often
●​ Only use acronyms if:
hides the actor).
○​ Shorter than full term.
○​ Example: "The mat (target) was sat on (verb)
○​ Used frequently in the document.
by the cat (actor)."
●​ Analogy: Acronyms are like nicknames—only helpful if
○​ Red Flag: Forms of be (is/are/was/were) +
everyone knows them.
past participle (e.g., "was interpreted").
2. Why Prefer Active Voice?
4. Ambiguous Pronouns
●​ Problem Pronouns: it, they, this, that. ●​ Advantages:
●​ Actionable Fixes: ○​ Clearer: Shows who’s doing what.
○​ Repeat the noun instead of using a pronoun ○​ Shorter: Fewer words (e.g., "Python
if unclear. compiles code" vs. "Code is compiled by
○​ Place pronouns close to their referent (≤5 Python").
words apart). ○​ Engaging: Feels more direct and dynamic.
○​ Add a noun after this/that: "This feature may ●​ Exception: Use passive when the actor is
be a security risk." unknown/unimportant (e.g., "The data was collected
●​ Example Fix: automatically").
○​ "Aparna and Phil share responsibilities with 3. Spotting Passive Voice
Maysam and Karan. Aparna and Phil are
●​ Formula: [Target] + [form of be + past participle] (+ by
next on call."
[actor]).
5. Exercise Fixes
○​ Example: "The bug (target) was fixed
●​ MapReduce Example:
(passive verb) by the developer (actor)."
●​ "Jeff Dean invented MapReduce (MR) in 1693... This
●​ Tip: Look for by phrases or missing actors (e.g.,
version of MR held..."
"Mistakes were made").
●​ Ambiguous Pronoun Example:
4. Fixing Passive Voice
○​ "They" could mean Aparna/Phil or
Maysam/Karan. Fix by specifying. ●​ Actionable Steps:
○​ Identify the actor (who’s doing the action?).

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 1

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ Move the actor to the subject position. iv.​ ✅ The system generates this error
○​ Rewrite the verb in active form.
●​ Example: v.​
vi.​
❌
message when...

✅ We are very careful to ensure...

We carefully ensure…
○​ Passive: "The report was submitted by the
2.​ Avoid “There is” / “There are”
team." a.​ These phrases lead to generic subjects and
○​ Active: "The team submitted the report." weak structure.
5. Imperative Verbs ≠ Passive b.​ Usually, you can delete or rearrange to reveal
a clearer sentence.
●​ Commands (e.g., "Click the button") are active voices
with an implied you as the actor.
c.​ Examples:
i.​ ❌ There is a variable called

Retention Boosters ii.​ ✅

met_trick that stores accuracy.
A variable named met_trick
●​ Mnemonic: "A.S.A.P." for clarity:
1.​ Actor first
d.​ 📌 stores accuracy.

❌
Practice Rewrites:
i.​ There is a lot of overlap

✅
2.​ Shorten sentences between X and Y.
3.​ Avoid be + past participle ii.​ X and Y overlap significantly.
4.​ Prefer directness
●​ Quiz Questions: 3.​ Minimize Vague Adjectives & Adverbs
a.​ Adjectives/adverbs = great in fiction, risky in
1.​ Convert to active: "The code was reviewed
technical writing.
by the engineer." b.​ They’re subjective and often sound like

📌
■​ Answer: "The engineer reviewed the marketing.
code." c.​ Avoid words like:
2.​ Is this passive? "Results were analyzed." i.​ amazing, screamingly fast,
■​ Answer: Yes (missing actor).
d.​ 📌 incredibly powerful
Example:
i.​ ❌ This flag makes the app run
Exercises & Answers
Exercise 1: Label as Active (A) or Passive (P). ii.​ ✅
screamingly fast.
This flag makes the app run
225–250% faster.
1.​ Mutable Input provides read-only access. → A
2.​ Read-only access is provided by Mutable put. → P SHORT SENTENCES
3.​ Performance was measured. → P 1.​ Why Short Sentences Matter
4.​ Python was invented by Guido van Rossum. → P ●​ Short code is easier to read, maintain, and
5.​ David Korn discovered the KornShell. → A less error-prone.
Exercise 2: Rewrite passive sentences as active. ●​ Same applies to writing:
○​ Shorter docs are easier to read and
1.​ "The flags weren’t parsed by the Mungifier." → "The maintain.
Mungifier didn’t parse the flags." ○​ Fewer lines = fewer points of
failure.
2.​ "A wrapper is generated by the Op process." → "The
○​ Short sentences are usually clearer
Op process generates a wrapper." and more powerful.

CLEAR SENTENCES 2.​ Focus Each Sentence on a Single Idea

1.​ Choose strong verbs ●​ Think of each sentence as doing one task,
a.​ The verb is the most important part of the like a line of code.

📌TheExample
sentence.
b.​ Avoid weak, generic verbs like: (before):​
i.​ Forms of be: is, are, am, was, were late 1950s was a key era for
ii.​ Occur, happen programming languages because IBM
c.​ Examples:
i.​ ❌ The exception occurs when
introduced Fortran in 1957 and John
McCarthy introduced Lisp the following year,

ii.​ ✅
dividing by zero.
Dividing by zero raises the
which gave programmers both an iterative
way of solving problems and a recursive way.

iii.​ ❌
exception.
This error message happens
when...
●​ After (shorter, clearer):
○​ The late 1950s was a key era for
programming languages.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 2

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ IBM introduced Fortran in 1957. ✅ Fortran is great for calculations that don’t
○​

○​
John McCarthy invented Lisp the
following year.
Programmers could now solve
✅
involve linear algebra. (essential)
Python is an interpreted language, which
Guido van Rossum invented. (extra detail)
problems iteratively or recursively. ●​ Rule of Thumb:
○​ If you pause before the clause →
3.​ Convert Long Sentences into Lists use which
●​ Look for "or", "and", or sequences of actions ○​ If no pause → use that
— these can often be rewritten as bullet or

●​ 📌
numbered lists.
Example (before):
○​ To alter the usual flow of a loop, you
LIST AND TABLES
1.​ Why Use Lists?
●​ Lists organize technical info clearly.
may use either a break statement ●​ Engineers and technical readers prefer
(which hops you out of the current clean, structured formats.
loop) or a continue statement ●​ Convert messy paragraphs into bulleted,
(which skips past the remainder of numbered, or embedded lists when
the current iteration of the current appropriate.

●​ 📌
use:
loop).
After (as a list), to alter the loop’s flow, 2.​ Types of Lists
●​ Bulleted Lists → for unordered items
○​ break: exits the current loop.
○​ continue: skips the rest of the
current iteration.
○​ ✅
○​ ➤ Order doesn’t matter
Example:
■​ Bash provides:
●​ String
4.​ Eliminate or Reduce Extra Words manipulation
●​ Cut unnecessary or bloated phrases. ●​ Substring deletion
●​ Replace with concise verbs. ●​ File reading
●​ Numbered Lists → for ordered steps

○​ ✅
○​ ➤ Sequence matters
Example:
■​ To reconfigure the server:
■​ Stop the server
■​ Edit the config file
■​ Restart the server

●​ Embedded Lists → items listed inside a

sentence
○​ ➤ Not ideal for technical info
○​ ➤ Better to convert to a bulleted or
5.​ Reduce or Break Subordinate Clauses
●​ Subordinate clauses add details, but ○​ ❌numbered list
Example:
The API can create llamas, query
sometimes clutter the sentence.
●​ Ask: Does this extend the main idea or llamas, analyze alpacas, and delete
distract from it?
○​ ✅vicunas.
Better:
●​ 📌
●​ If it’s a new idea → make it a new sentence.
Example:
Python is an interpreted programming
The API allows you to:
■​ Create and query llamas
language, which was invented in 1991. ■​ Analyze alpacas
○​ Main idea: Python is interpreted. ■​ Delete vicunas
○​ Extra detail: invented in 1991 → 3.​ Keep List Items Parallel
could be a new sentence. ●​ All list items should be consistent in
●​ Common Subordinate Clause Starters: grammar, capitalization, punctuation, logical
○​ which, that, because, unless, since,
whose, until ●​ ✅
type
Parallel:
○​ Carrots
6.​ Distinguish “That” vs “Which” ○​ Potatoes
●​ That → essential info (no comma)
●​ Which → extra, nonessential info (add ●​ ❌ ○​ Cabbages
Nonparallel:
○​ Carrots
●​ 📌
comma)
Examples: ○​ Potatoes

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 3

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ The summer light obscures all ●​ It should clearly state the main idea of the
memories of winter. paragraph.

4.​ Use Imperative Verbs in Numbered Lists

●​ Imperative = command verbs (e.g., Open,
●​
●​ ✅
Sets the topic or theme of what’s to come.
Effective:
○​ A loop runs the same block of code

●​
Start, Change)

✅
●​ Helps guide users step-by-step
Parallel list:
●​ ❌ multiple times.
Defective:
○​ A block of code is any set of
1.​ Stop Frambus. contiguous code within the same
2.​ Open the config file. function. ← not the real topic
3.​ Change Carambola to 64.
4.​ Save and close the file. 2.​ Focus Each Paragraph on a Single Topic
5.​ Stop Frambus. ●​ Stick to one idea per paragraph.
●​ Avoid jumping to past or future topics.
5.​ Punctuate List Items Properly ●​ Cut or move sentences that don’t directly
●​ Capitalize the first word of each list item
●​ Use periods only if the list item is a full ●​ 📌
support the main point.
Example — focused on the Pythagorean

●​ ✅
sentence
Example:
○​ Loops
●​ ✅
Theorem:
Keep:
○​ Theorem definition

●​ ✅
○​ Conditionals
○​ Variable declarations
With sentences:
●​ ❌ ○​ Application to diagonal distances
Remove:
○​ Perimeter formulas → not related
○​ Click the “Run” button. to diagonals
○​ Enter your password. ●​ Always check if each sentence supports the
main topic.
6.​ Use Tables Wisely
●​ Engineers love tables for quick comparisons 3.​ Paragraph Length: Not Too Long, Not Too Short
●​ Label each column clearly ●​ Too Long = wall of text = intimidating
●​ Avoid long blocks of text in cells ➤ Split into 2 paragraphs if >7 sentences
●​ Keep data types consistent in each column ●​ oo Short = lacks depth
➤ Merge with nearby related content or

●​ 📌
consider a list
Ideal length: 3–5 sentences

4.​ Answer What, Why, and How

●​ Great paragraphs answer:
●​ What is the concept or point?
●​ Why does it matter to the reader?

7.​ Introduce Lists & Tables Clearly

●​ 📌
●​ How should the reader use or trust this?
Example:
○​ What: The garp() function returns
●​ Always add a sentence to introduce your list
the delta between mean and
or table
median.
●​ Use a colon at the end
○​ Why: People wrongly assume the
●​ ✅
●​ Include the word "following" when possible
Examples:
○​ The following list shows required
mean is always reliable.
○​ How: Use garp() to test whether
extreme values are skewing the
tools:
○​ Take the following steps to reset
the system:
●​ ✅ mean.
This makes the paragraph more
complete and useful.
○​ The following table compares
supported platforms:
AUDIENCES
1.​ Know Your Audience
PARAGRAPHS
●​ Why: You write differently depending on
1.​ Write a Great Opening Sentence
who’s reading—tech leads ≠ new users.
●​ The first sentence is the most
●​ Actionable:
important—busy readers may only read that.
○​ Consider your reader’s role, goals,
and background.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 4

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ Tailor tone and level of detail ■​ Readers understand

accordingly. matrix multiplication and
backpropagation.
2.​ Three Audience Types ○​ Prerequisite Reading:
1.​ Managers ■​ You must read "Project
○​ Want high-level summaries, Froobus: A New Hope"
outcomes, impact. prior to reading this
○​ Ask: What does this mean for document.
timelines, teams, and goals?
2.​ Peers (Engineers) 3.​ Summarize Keep Points at the Start
○​ Prefer details, specifics, why ●​ Many readers won’t finish the entire
choices were made. document.
○​ Ask: How does this work? Could we ●​ Ensure the first paragraph answers key
improve this? questions and summarizes the main ideas.
3.​ Newbies (New Engineers, Interns) ●​ Page 1 is often the hardest and most
○​ Need clear explanations, important—be ready to revise it multiple
definitions, step-by-step help. times.
○​ Ask: What does this term mean?
How do I use this? 4.​ Compare and Contrast
●​ Most documents are evolutionary, not
DOCUMENTS revolutionary.
1.​ State the Scope ●​ Comparing helps the audience connect new
●​ Scope: What the document does cover. ideas to things they already know.
●​ Non-scope: What the document does not ●​ Example
○​ This new app is similar to the
●​ ✅
cover but readers might expect it to.
Example
○​ Scope: This document describes
Frambus app, except with better
graphics.
the design of Project Frambus. ○​ The Froobus API handles the same
○​ Non-scope: This document does use cases as Frambus, but is easier
not describe the design for the
related technology, Project ●​ ⚠️ to use.
Common Mistake (Example Exercise)
"Frambus Weather app v2 introduces ten
Froobus.
●​ Why It Matters features not available in v1. Most importantly,
○​ Keeps the writer focused. v2 offers two-week forecasts, v1 offered only
○​ Helps the reader understand the one-week forecasts. Tidal information won't
document's boundaries. change."
○​ During revision, delete anything Issue: The sentence lacks clarity. It needs
better separation of ideas (e.g., punctuation
●​ ⚠️ outside of scope.
Common Mistake (Example Exercise)
"This document explains how to use the
or phrasing).

Frambus API to create, update, and publish 5.​ Write for your Audience
Fwidgets. This document does not explain ●​ Do an Audience-Oriented Planning
how to use the Frambus API to delete ●​ Answer these before writing:
Fwidgets or cover the history of the Linux ○​ Who is your target audience?
operating system." ○​ Why are they reading the
Issue: The second topic (Linux history) is document?
completely unrelated and distracts from the ○​ What do they already know?
scope. ○​ What should they know or do after

2.​ State the Audience ●​ ✅

Algorithm
reading?
Example Scenario: New Sorting
●​ Clearly state who the document is for.
●​ Include job roles, background knowledge, or ○​ Audience: Software engineers in
your org.
●​ ✅
prerequisites.
Example
○​ Target Audiences:
○​ Goal: They want a more efficient
sorting algorithm.
■​ Software engineers ○​ Prior Knowledge: Familiar with
■​ Program managers sorting concepts like quicksort, but
○​ Assumptions: rusty.
○​ After Reading: They can:
■​ Compare it to quicksort

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 5

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

■​ Know when it's better ○​Protocol Buffers—also called

■​ Implement it protobufs—are efficient.
■​ Understand its limitations 4.​ EN DASHES (–) and HYPHENS (-)
●​ Hyphens join compound words:
6.​ Organize Content to Meet Audience Needs
●​ Based on the example, organize the decision-making system, self-attention
document like: ●​ En dashes are generally avoided in technical
1.​ Overview of the algorithm writing (per Google Style Guide).
2.​ Compare with quicksort (include Big O) ●​ When in doubt, check a dictionary or official
3.​ Link to reference material (e.g., Wikipedia) glossary.
4.​ Describe best datasets 5.​ COLONS
5.​ Pseudocode
●​ Introduce a list or explanation:
6.​ Implementation tips
7.​ Deeper technical analysis ○​ Use the following tools: Python,
8.​ Edge cases and performance issues Java, and C++.
9.​ Known unknowns ●​ Don’t use a colon if the sentence flows
naturally:
○​ My favorite languages are Python
PUNCTUATION and Java.
1.​ COMMAS 6.​ PARENTHESES
●​ Use commas for short pauses, separating ●​ Hold side comments or minor info:
elements in a sentence. ○​ (Protocol Buffers make great
●​ Common uses: birthday gifts.)
○​ In lists: Python, Java, and C++ ●​ Period placement rules:
(Oxford comma recommended) ○​ Inside if the whole sentence is inside
○​ After introductory phrases or the parentheses.
conditions: If the program runs ○​ Outside if only part of the sentence
slowly, try the --perf flag. is inside.
○​ Around nonessential information:
Python, an easy-to-use language, is MARKDOWN
gaining popularity. 1.​ What is Markdown?

❌
●​ Avoid comma splices: ●​ Allows formatting like headers, bold text,
○​ Samantha is a great coder, she and lists using plain text.

✅
writes tests. ●​ Common in technical
○​ Samantha is a great coder. She environments—especially for writing
writes tests. documentation in tools like GitHub, Jupyter,
2.​ SEMICOLONS and static site generators.
●​ Join two related independent clauses:
○​ Update the config file; then rerun
Frambus.
●​ Reversible logic test: The sentence should
still make sense if flipped.
●​ Use before transitions like however,
therefore, and follow with a comma:
○​ Code changes can cause bugs;
therefore, write tests.
●​ Don’t use in regular lists—use commas
instead.
3.​ EM DASHES (—)
●​ Indicate a stronger pause than a comma:
○​ C++ is a rich language—one that
demands experience.
2.​ Why Use Markdown?
●​ Often replace parentheses or commas for
●​ Clean and readable, even without rendering.
emphasis:

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 6

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

●​ Can be converted into HTML for viewing in ○​ Common style principles (some from
browsers. Technical Writing One):
●​ Ideal for documentation, README files, i.​ Use an active voice to show who
wikis, and tech notes. does what.
ii.​ Example: “Install the package.” (not
SUMMARY “The package is installed.”)
Technical Writing One covered the following basic lessons of iii.​ Use numbered lists for step-by-step
technical writing: instructions.
●​ Use terms consistently. iv.​ Use bulleted lists for unordered
●​ Avoid ambiguous pronouns. items or features.
●​ Prefer active voice to passive voice. v.​ Use second person ("you") — not
●​ Pick specific verbs over vague ones. “we” — to speak directly to the
●​ Focus each sentence on a single idea. reader.
●​ Convert some long sentences to lists. vi.​ Place conditions before
●​ Eliminate unneeded words. instructions.
●​ Use a numbered list when ordering is important and a vii.​ Example: “If the server is down,
bulleted list when ordering is irrelevant. restart it.” not “Restart the server if
●​ Keep list items parallel. it is down.”
●​ Start numbered list items with imperative words. viii.​ Use code font for code, commands,
●​ Introduce lists and tables appropriately. and technical names (e.g.,

✅
●​ Create great opening sentences that establish a [Link]).
paragraph's central point. ○​ Tip: For small projects, highlights of a
●​ Focus each paragraph on a single topic. style guide may be enough.
●​ Determine what your audience needs to learn. 2.​ Think Like Your Audience
●​ Fit documentation to your audience. ○​ Always ask: Who will read this?
●​ Establish your document's key points at the start of ○​ Ensure the purpose of your doc is obvious.
the document. ○​ Define unfamiliar terms clearly.
○​ You can create a simple audience persona:
TECHNICAL WRITING 2 i.​ Role: e.g., QA Tester, Backend
●​ Designed for technical professionals who want to Developer
further improve their writing skills. ii.​ Goal: e.g., Troubleshoot database
●​ Builds on concepts learned in Technical Writing One. errors
●​ Emphasizes intermediate-level techniques for writing iii.​ Assumptions: e.g., Uses Linux,
and editing technical documents. Knows Python, Comfortable with
command line
SELF-EDITING iv.​ Tailor your document based on that
What is Self-Editing? persona.
●​ After writing a first draft, editing is necessary to refine v.​ Add links or resources if the
your content. audience might need more

⚠️
●​ Good writing doesn’t come out perfect immediately — background knowledge.
it’s shaped through revision and feedback. ○​ Caution: Don’t make your document too
●​ Use one or more strategies to edit; what matters is specific to only one persona — it may
finding a routine that works and using it consistently. exclude others.
3.​ Read It Out Loud
Key Self-Editing Strategies ○​ Reading aloud helps catch:
1.​ Adopt a Style Guide i.​ Awkward phrasing
○​ A style guide standardizes how your ii.​ Long or confusing sentences
documents look and sound. iii.​ Dull or overly robotic tone
○​ Companies or teams usually follow an ○​ You’ll also hear whether your writing sounds:
existing guide (e.g., Google Developer i.​ Conversational (good for guides,
Documentation Style Guide) or make their open-source docs)
own.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 7

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

ii.​ Formal (better for

💡
business/enterprise docs)
○​ Try using a screen reader as an
alternative.
4.​ Come Back to It Later
○​ Don’t edit immediately after writing.
○​ Take a break — even a few hours helps.
○​ Fresh eyes = better judgment.
○​ You’ll see mistakes you couldn’t earlier.
5.​ Change the Context
○​ Seeing your writing in a different format
makes mistakes easier to spot.
○​ Examples:
i.​ Print it out and edit on paper
ORGANIZING LARGE DOCUMENTS
ii.​ Change font size, style, or color in
Writing One Long Document vs. Multiple Shorter Documents
the document
●​ Choose your format based on audience and content:
6.​ Find a Peer Editor
●​ Long documents are suitable for:
○​ Just like code review, technical writing
○​ In-depth tutorials
needs peer feedback.
○​ Best practice guides
○​ Ask someone familiar with your style guide
○​ Reference pages (not always read linearly)
(but not necessarily a technical expert) to
●​ Short documents are better for:
review your work.
○​ Beginners needing brief guides
○​ Request specific and constructive
○​ Quick-starts or conceptual overviews
comments, not just “It’s good.”
●​ Reader preferences differ:
○​ Hong prefers search over reading long
Practice Exercise (Sample Paragraph Rewrite)
documents.
Original Paragraph:
○​ Rose likes reading long docs and uses "Find
on page."
“Determine whether or not you can simplify your document
●​ Guidelines:
through the use of terminology that is equivalent but relatively
○​ Break down long tutorials if possible.
shorter in length and therefore more easily comprehensible by
○​ Use narrative for long documents to improve
your audience. It's important to make sure your document is
flow.
edited before it is seen by your audience, which might include
○​ Use short, focused docs for new users
people that are less or more familiar with the matter covered
unfamiliar with concepts.
by your document. The first thing you need is a rough draft.
Some things that can help make your document easier to read
Organizing a Document
are making sure you have links to background information, and
●​ Start with an Outline
also checking for active voice instead of passive voice. If you
○​ Create a high-level structure before writing.
have long sentences you can consider shortening them or
○​ Group related topics and tasks together.
implementing the use of a list to make the information easier
to scan.”
Tips:
✨ Suggested Edit (improved version):
○​ Explain the "why" before asking the reader to
do something.
○​ Each step in the outline should represent:
Start with a rough draft. Then, simplify your language by
■​ One concept OR
choosing shorter, clearer terms. Edit your document before
■​ One action/task
sharing it with your audience, which may include readers with
○​ Place advanced or historical info later in the
varying levels of familiarity. To make your writing easier to
document.
read, use active voice, provide links to background information,
and break up long sentences. Use lists where appropriate to
●​ Share Outline with Others
help readers scan the content.
○​ Especially useful for team projects.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 8

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ Encourages feedback and alignment early in ■​ Visuals

the writing process. ○​ Simplify long processes by:
■​ Breaking them into sub-tasks
Introduce a Document Properly ■​ Using simple examples first,
●​ A good introduction should clearly state: complex ones later
○​ What the document covers
○​ Required prior knowledge
○​ What the document does not cover
●​ Example:
“This guide teaches you how to publish Markdown files
using Froobus on a Linux system. You need to know
Markdown and basic terminal commands. This guide
won’t cover how to install Froobus—see the 'Getting

✅
Started' guide for that.”
●​ After writing:
○​ Review your introduction vs. final draft.
○​ Ensure the intro sets accurate expectations.
ILLUSTRATING
Why Illustrations Matter
Add Clear Navigation
●​ Readers, like students flipping through textbooks,
●​ Helps readers find what they need and not get lost in
often prefer images over plain text, especially in
large docs.
technical documents.
●​ Good navigation includes:
●​ Research shows: any image can make a document
○​ Clear headings and subheadings
more likable, but only instructive graphics actually
○​ Logical content progression
improve learning (Sung & Mayer, 2012).
○​ Table of contents
●​ Good graphics can say what 1000 words cannot.
○​ Intro and summary
○​ Internal links to:
Write the Caption First
■​ Definitions
●​ Before drawing anything:
■​ Related topics
○​ Write the caption first to clarify what the
■​ Next steps
image should convey.
●​ Use Task-Based Headings
○​ Then, make sure your illustration reflects
○​ Use clear, action-oriented titles (e.g.,
that purpose.
“Creating the Site”)
●​ Good captions should be:
○​ Avoid technical terms unless your audience
○​ Brief (just a few words)
is advanced
○​ Clear on the takeaway (What should the

✅
●​ Example:
reader remember?)

❌
●​ “Creating the Site”
○​ Focused (Especially if the image has a lot
●​ “Running the carambola command”
📌
going on)
●​ Add Context Under Each Heading
●​ Reminder: The caption always goes under the
○​ Don’t jump directly to subtopics
diagram.
○​ Add 1–2 sentences to orient readers
Limiting Information in One Image
Disclose Information Progressively
●​ Overloading a diagram = visual clutter = confused
●​ Prevents overwhelming the reader with too much at
readers.
once.
●​ Think of illustrations like paragraphs: keep it focused
●​ Techniques:
and digestible.
○​ Introduce concepts as needed, not all at the
●​ Rules of thumb:
beginning
○​ Don’t cram more than one paragraph’s worth
○​ Break up text walls with:
of ideas in a single figure.
■​ Lists
○​ Avoid images that would need more than
■​ Tables
📌
five bullet points to explain.
■​ Headings
●​ If your system is complex:

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 9

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

○​ Start with a simple overview or “big picture”

diagram. CREATING SAMPLE CODE
○​ Then, show each subsystem separately in What Makes Good Sample Code?
zoomed-in diagrams. ●​ Good sample code is:
■​ Example: A large network diagram ○​ Correct – Does what it says and follows
→ then break it down into smaller, best practices.
labeled subsystems. ○​ Concise – Short and focused, includes only
what’s necessary.
Focus the Reader’s Attention ○​ Understandable – Easy to read and follow.
●​ Readers can get lost in visuals without guidance. Use ○​ Commented – Has helpful, relevant
these methods to guide focus: comments.
●​ 1. Visual cues: ○​ Reusable – Can be used by others with
○​ Add shapes (like red ovals) or highlights to minimal adjustments.
direct the eye. ○​ Sequenced – Demonstrates increasing
●​ 2. Callouts: complexity to support learning.
○​ Use arrows and labels that point out the
important parts. 1.​ Correct Code
○​ Helps avoid long, wordy explanations. a.​ Your sample code must:
○​ Especially useful in screenshots, diagrams, i.​ Build and run without errors.
or complex photos. ii.​ Actually perform the task it claims
●​ Example: A red oval around a menu item helps the to do.
reader know where to look first. iii.​ Be production-ready (no security
issues, poor practices, etc.).
Illustration = Re-illustration (Just like writing = rewriting) iv.​ Follow coding conventions of the
●​ Your first draft illustration probably won’t be the best. specific language.
Always revise! v.​ Be tested regularly—code samples

⚠️
●​ Ask yourself: often break over time.
○​ Can I simplify it? b.​ Warning: Don’t confuse unit tests with
○​ Should I split this into multiple diagrams? sample code. Unit tests test functionality;
○​ Is the text readable and high-contrast? sample code teaches functionality.

📍
○​ Is the main idea clear? c.​ Snippets (tiny samples, a few lines only) are
●​ Example: London Tube Map okay but risky—they’re often not tested
○​ Old version: to-scale with above-ground thoroughly and may degrade in quality over
markers (confusing) time.
○​ Harry Beck’s redesign (1931): simplified with 2.​ Running the Sample Code
clear lines and better readability. a.​ Help your readers run the code easily. If
■​ Focused on what users cared setup is needed, clearly state it, such as:
about—getting from Point A to i.​ Installing libraries
Point B. ii.​ Setting environment variables
●​ Even Beck continued revising the map for years to iii.​ IDE configuration steps
improve clarity. You should revise your graphics too. b.​ Optionally, let users run the code directly
inside documentation (interactive docs).
Tools for Making Graphics c.​ Also, include the expected output or
●​ You can use these free tools to make diagrams: behavior—especially useful when readers
○​ Google Drawings can't run the code immediately.
○​ [Link] 3.​ Concise Code
○​ LucidChart a.​ Only include necessary lines—avoid extra
●​ Best export format: code that distracts.
○​ Use SVG (Scalable Vector Graphics) for b.​ Don’t shorten code by sacrificing
clean, high-quality images that scale well at correctness.
any size. c.​ Avoid including large codebases when a
short snippet would teach the same thing.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 10

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

d.​ ✅ Example: Show how to use malloc() with a.​ Sometimes it’s helpful to show:
a few lines, not the full Linux kernel. i.​ A correct version of code
4.​ Understandable Code ii.​ An incorrect (anti-) example of how

📌
a.​ To make code readable and understandable: not to do it
i.​ Use clear, descriptive names for b.​ Example (for Bash):
classes, variables, methods.
ii.​ Avoid tricky or advanced
programming techniques that
confuse beginners.
iii.​ Keep code flat (avoid deep
nesting).
iv.​ You may use highlighting (bold,
colors) to draw attention, but don't
overdo it.
5.​ Commenting Code
a.​ Good comments help readers understand 8.​ Sequenced Complexity
why the code is written a certain way, a.​ Don’t just show one example—build up from
especially for beginners. easy to hard.
b.​ Tips: b.​ A good sequence of functions for a tutorial
i.​ Be clear and brief. might include:
ii.​ Skip obvious comments (but i.​ A function with no parameters and
remember what’s “obvious” to you no return value
may not be to a newbie). ii.​ A function with one parameter and
iii.​ Focus comments on non-intuitive no return value
logic. iii.​ A function with one parameter and
iv.​ For expert audiences: explain the a return value
reasoning, not just what the code iv.​ A function with three parameters
and a return value
📍
does.
c.​ Where to place the explanation? c.​ This approach helps learners grow their
i.​ For short explanations: embed understanding step by step.
them directly as code comments.
ii.​ For longer or complex
explanations: place them before
the sample code in paragraph or
list form.
d.​ If you intentionally make the code simpler by
skipping best practices (e.g., removing input
checks), explain that in the comments.
6.​ Reusable Code
a.​ Your sample should be easy to adapt and
reuse by others. To help with this:
i.​ Provide all setup info (libraries,
versions, dependencies, configs).
ii.​ Avoid side effects (like crashing
someone’s app).
iii.​ Make sure your code doesn't:
1.​ Leak sensitive data SUMMARY
2.​ Break when reused in a Technical Writing Two covered the following intermediate
real app lessons of technical writing:
3.​ Introduce security or ●​ Adopt a style guide.
performance issues ●​ Think like your audience.
7.​ Good vs. Bad Examples ●​ Read documents out loud (to yourself).

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 11

 PUBLIC HEALTH AND REGULATORY PHARMACY
Institute of Pharmacy S.Y. 2025-2026
4th Year I 1st Sem Internship

●​ Return to documents well after you've written the

draft.
●​ Find a good peer editor.
●​ Outline a document. Alternatively, write free form and
then organize.
●​ Introduce a document's scope and any prerequisites.
●​ Prefer task-based headings.
●​ Disclose information progressively (in some
situations).
●​ Consider writing the caption before creating the
illustration.
●​ Constrain the amount of information in a single
drawing.
●​ Focus the reader's attention on the relevant part of a
picture or diagram by describing the takeaway in the
caption or by adding a visual cue to the picture.
●​ Create concise sample code that is easy to
understand.
●​ Keep code comments short, but prefer clarity over
brevity.
●​ Avoid writing comments about obvious code.
●​ Focus your commenting energy on anything
non-intuitive in the code.
●​ Provide not only examples but also anti-examples.
●​ Provide code samples that demonstrate a range of
complexity.
●​ Make a practice of continuous revision.
●​ Provide different documentation types for different
categories of users.
●​ Compare and contrast with something that readers
are already familiar with.
●​ In tutorials, reinforce concepts with examples.
●​ In tutorials, note problems that readers may
encounter.

PHARM 6 LECTURE TRANSCRIBED BY: BATCH 1 12