Forem: Khaled Abdel-Fattah

For Muslims: Stay Consistent With Salah at Work Using This Slack App

Khaled Abdel-Fattah — Sat, 21 Feb 2026 21:50:04 +0000

It is 4:47 PM.

You are fasting.
Energy is low.
There is one more meeting before the day ends.
Slack notifications keep coming in.

Then you check the time.

Asr started 20 minutes ago.

You meant to pray on time.
But work did not slow down.

For many Muslim professionals, Ramadan does not pause deadlines. It makes the balance between work and worship more challenging.

That is exactly why I built Muslim Prayer Reminder for Slack.
A Slack app designed to help you stay consistent with salah without leaving your workspace.

Why a Prayer Reminder Inside Slack?

If you spend most of your day in Slack, it becomes your main environment.

Opening another app to check prayer times:

Interrupts your workflow
Gets forgotten
Feels disconnected from your workday

Instead, prayer reminders appear directly inside Slack.

No loud alarms.
No intrusive popups.
Just a respectful notification at the right time.

Pre-Adhan Reminders: Prepare Before Prayer Time

One of the newest features, especially helpful during Ramadan, is Pre-Adhan Reminders.

You can choose to receive a reminder:

5 minutes before prayer
10 minutes before
15 minutes before
20 minutes or more

That small buffer gives you time to:

Finish a task
Wrap up a meeting
Make wudu calmly
Mentally shift from work mode to worship

During Ramadan, that transition matters. It removes rush and brings intention back into the moment.

🤝 Join Jama’ah: Find Colleagues to Pray Together

Many Muslim employees do not always know who else wants to pray.

With the Join Jama’ah button:

When prayer time arrives, you click once
A simple message is posted
Others can respond and join

No awkward conversations.
No guessing.
Just a clear signal that you are heading to pray.

The Prophet ﷺ said that prayer in congregation carries greater reward. Even in modern offices or remote teams, that opportunity should not be lost.

🕌 Set Status: Praying

Another powerful feature for Ramadan is Set Status: Praying.

With one click:

Your Slack status becomes 🕌 Praying
You select a duration from 10 to 60 minutes
It automatically resets when time ends

This creates clarity.

Your team understands you are temporarily unavailable.
There is no need to explain or apologize.
Prayer becomes part of your routine, not an interruption.

Accurate, Location-Based Prayer Times

Muslim Prayer Reminder for Slack calculates prayer times based on your country and preferred calculation method.

You configure it once using the /prayer command.

You can choose:

Which prayers to receive
Channel or direct message notifications
Arabic or English language
Your preferred calculation method

Whether you are in Cairo, Dubai, London, Toronto, or working remotely across time zones, prayer times adjust automatically. This is especially important during Ramadan when Maghrib timing determines Iftar.

Install Muslim Prayer Reminder for Slack

You can install the Slack app here:

👉 https://muslium-prayer-reminder.onrender.com/slack/install

Setup takes less than two minutes:

Add the app to your Slack workspace
Use /prayer to set your location
Choose your prayer preferences
Enable Pre-Adhan, Join Jama’ah, and Set Status features

That is it.

Meetings will continue.
Emails will continue.
Slack will continue.

Ramadan will leave.

If a simple reminder inside your workspace helps you pray on time, break your fast on time, and pray in congregation when possible, then technology is serving your deen.

Ramadan Kareem 🌙
May Allah accept our fasting, our prayers, and our efforts.

Writing Docs in a World Where LLMs Are the Readers

Khaled Abdel-Fattah — Sun, 04 Jan 2026 19:59:59 +0000

Writing documentation is no longer just for humans.

Developers still read it, but AI reads it too. Large language models scan, summarize, and even generate code from your docs.

This shift does not make documentation less important, it changes how we write and structure it. In this article, you’ll learn how llms.txt helps your docs work for both humans and machines.

1. How Google Cloud Is Adapting Documentation for AI

The Google Cloud Developer Experience team focuses on one goal: helping developers move from learning to launching as fast as possible.

As Google Cloud services grew, keeping documentation accurate and up to date became harder. Developers expect quick, correct answers. If docs fall behind, adoption suffers.

Google Cloud did not replace technical writers.

They augmented them with AI.

Generative AI is now part of their documentation workflow. It helps with formatting, markup translation, and validation. Some docs are even tested automatically by running the documented steps in real environments.

Documentation is treated like code: generated, tested, and continuously improved.

You may not work at Google Cloud scale, but the same pressures already exist in many teams today.

2. Documentation Is No Longer Read Only by Humans

Developers still read documentation. But very often, AI reads it first.

Today, developers:

Ask AI to generate and debug code
Let AI research APIs and tools
Paste full documentation pages into prompts

Human readers are still important. But LLMs are now a primary consumer of documentation.

Documentation is no longer just read by humans. It is consumed by LLMs.

That reality changes how docs should be structured and published.

3. Tech Writers Do Not Compete With AI. They Enable It.

It is easy to worry that AI will replace tech writers.

In practice, the opposite is happening.

AI can generate text quickly. It cannot decide what matters, what is correct, or how concepts should be structured.

Tech writers provide that structure.

Tech writers do not need to compete with AI. They need to organize knowledge so AI can use it correctly.

This shift moves the role from writing pages to designing knowledge systems.

One common way to do this is by providing AI tools with a structured, machine-readable version of your docs. This is where llms.txt comes in.

4. What `llms.txt` Is and What It Is Not

llms.txt is a machine-readable version of your documentation. It is usually written in Markdown and designed for AI tools and LLMs.

Think of it as a translation layer:

Your main documentation stays human-friendly
llms.txt gives AI a clean and structured view of the same content

A good llms.txt file often includes:

Core concepts and terminology
API overviews and constraints
Authentication and environment assumptions
Canonical examples
Known limitations and edge cases

What it is not is just as important.

This does not replace documentation.

It protects it.

By giving AI its own context file, you avoid turning human docs into prompt-shaped content. Human readers get clarity. AI tools get structure.

5. Make `llms.txt` Auto-Generated

One key lesson from Google Cloud is automation.

Their documentation is generated, validated, and tested continuously. llms.txt should follow the same idea.

Best practice is to auto-generate it whenever documentation changes.

Practical guidance:

Generate llms.txt as part of your docs build process
Regenerate it on every docs edit
Preserve headings, code blocks, links, and examples in Markdown
Add simple checks to ensure the file is complete

This matters because:

AI relies on fresh context
Manual updates drift over time
Automation keeps humans and AI aligned

One source of truth.

Two audiences.

No duplication.

6. Lessons from Google Cloud’s AI Code Systems

Google Cloud also applied AI to code samples.

They faced thousands of APIs, many languages, and constant change. Manual maintenance did not scale.

Their solution used AI systems that:

Generate samples from official API definitions
Review and refine results automatically
Test code before publishing

The lesson is simple.

AI works best when knowledge is structured, grounded, and validated.

That same principle applies to documentation. llms.txt provides that structure for AI tools.

7. How to Use `llms.txt` in Practice

For AI tools with limited capabilities that cannot fetch docs on their own, llms.txt is especially useful.

A simple workflow:

Open docs.example.com/llms.txt
Download/Copy the Markdown file
Upload it into your AI coding tool
Ask the tool to analyze, debug, or generate code using this context

This keeps AI output aligned with real documentation and real constraints.

8. Make It Easy to Find

For llms.txt to be useful, it must be visible.

Recommended approach:

Publish it at docs.example.com/llms.txt
Keep it in Markdown format
Add a visible button in your docs like “AI Context (llms.txt)”
Open it in a new tab

This is not a power-user trick.

It is basic documentation infrastructure.

AI is not removing the need for tech writers.

It is raising expectations.

The work shifts from writing more pages to:

Structuring knowledge clearly
Designing systems that scale
Making documentation reliable for humans and machines

llms.txt is a small file, but it represents a real shift.

If you own documentation today, the question is not whether AI will read it.

It already does.

The real question is whether it is reading the right version.

Muslim Prayer Reminder for Slack

Khaled Abdel-Fattah — Tue, 23 Dec 2025 23:21:59 +0000

Work can get busy, meetings run long, and time passes quickly. For many Muslims, this makes it easy to miss prayer times during the day. Muslim Prayer Reminder for Slack was built to solve that problem in a simple and respectful way.
It sends prayer reminders directly to Slack, so you stay aware of prayer times without leaving the tool you already use for work.

Installation Link: https://muslium-prayer-reminder.onrender.com/slack/install

Why a Prayer Reminder in Slack?

If you spend most of your day in Slack, checking another app for prayer times can feel disruptive. This app keeps everything in one place.

No switching between apps
No loud or intrusive alerts
Gentle reminders during the workday
Suitable for office and remote work

It helps you stay mindful while keeping your focus on work.

What the App Does

Automatic Prayer Reminders

You receive notifications for the daily prayers at the right time, based on your location.

Location-Based Prayer Times

Set your country once, and prayer times are calculated accurately for your area.

Custom Settings

You decide:

Which prayers to be reminded about
Whether notifications go to a channel or direct message
Arabic or English language

How It Works

Getting started is quick:

Add the app to Slack: Install Muslim Prayer Reminder in your workspace (using this link)
Set your preferences: Use the /prayer command to choose your location, prayers, and language.
Receive reminders: Prayer notifications appear in Slack at the times you selected.

That’s it. No complicated setup.

A Simple Reminder of What Matters

The Prophet Muhammad ﷺ said:

“The prayer in congregation is twenty-seven times superior to the prayer offered by a person alone.”
(Bukhari & Muslim)

Work is important, but prayer should not be forgotten. This app helps you stay aware of prayer times, even on busy days.

Should I Be Proud If I Didn’t Really Work for It?

Khaled Abdel-Fattah — Sun, 07 Dec 2025 06:17:38 +0000

I have a confession.
When I built my “Muslim Prayer Reminder” Slack bot, and posted about it, people started reacting, congratulating me… and I didn’t really feel like a developer. I felt more like someone cheating on a school exam. I clicked a few buttons, approved suggestions, and suddenly I had a working app. A real product. In minutes.

It was fast. Too fast.
And that speed brought something weird. I wasn’t celebrating. I was questioning myself.

Should I be proud?
Did I actually build anything?
Or did I just watch the AI Agent do the heavy lifting while I sat there like a manager eating sunflower seeds?

All I really brought was the idea.
No deep knowledge.
No long nights.
No tough bugs.
No “I fixed it at 3 AM” badge of honor.

Just Continue… Yes… Okay… Done.

A part of me felt impressed.
But another part felt guilty, like I tricked everyone, including myself. Why celebrate work that didn’t cost effort or skill?

Then I took a step back.
Even if I didn’t write the code, something real happened: my idea became a product. I saw how possible it is to build things without being an expert. And that changed how I think about ownership.

Is ownership about typing every line?
Or is it about the idea, the intention, the vision behind it?

If you have an idea today, you can bring it to life faster than ever. You don’t need to wait until you master twenty frameworks. You don’t need years of deep technical knowledge to try things. You can test concepts, build tools, and create value without feeling blocked.

So yes, maybe I didn’t “earn” this bot in the traditional way.
But the idea was mine.
The direction was mine.
The product exists because I started it.

And maybe that’s enough to be proud of.

If you’ve been feeling the same guilt or confusion when you create something quickly, I get you. But don’t let that stop you from experimenting. The world is moving fast, and you’re allowed to move fast too.

Just build.
Just try things.
Your ideas matter, even if the work looks different now.

Too Many Em Dashes, Not Enough Sense

Khaled Abdel-Fattah — Mon, 27 Oct 2025 20:35:16 +0000

Life — like coffee — is best enjoyed — one reflection — at a time.

You felt that, didn’t you? Those dramatic pauses that make you wonder if the sentence is deep or just dizzy.

That’s the em-dash effect. The unofficial stamp of AI-generated writing. Every post suddenly sounds like it’s giving a TED Talk about nothing.

The funny thing? Most people using them don’t even know how to type one. They just let AI handle it. Ask them where the em-dash key is, and they’ll probably open Google.

Now it’s everywhere. LinkedIn posts, Instagram captions, even company emails that sound like motivational posters. Nobody edits anymore. Just copy, paste, and post.

I miss commas. I miss periods. They used to bring peace. Now every paragraph sounds like a speech written by a confused robot.

So if your text sounds like it’s out of breath, maybe read it again. Trim the dashes. Add a period or two.

Stop the punctuation panic. Save your sentences. Save us all.

No em dashes were harmed in the making of this post.

In the Age of AI, Why Bother Learning to Write?

Khaled Abdel-Fattah — Sat, 05 Jul 2025 20:17:24 +0000

If AI can write your blog post, your LinkedIn update, and even your product documentation… why bother learning to write at all?

It’s a fair question, and one I asked myself before writing this blog.

We’re living in a time when AI can spit out full articles, emails, and yes, even this sentence, faster than you can open Google Docs. It’s fast, it’s polished, and it even throws in a few buzzwords for good measure.

So it’s easy to think:

Why not let AI do the writing while I go make a sandwich?

Here’s the thing:

Just because you can generate 100 lines of text doesn’t mean anyone’s going to read them.
Not your audience. Not your boss. Not even you, especially not you.

Because writing isn’t just about stacking words together. It’s about saying something useful, to the right person, at the right time, in a way that actually lands.

And that’s something AI still struggles with. It can write for you, but it can’t write like you.

As a technical writer, I’ve seen this first-hand. I’ve seen docs that look clean but confuse readers. Or posts that sound “smart” but say absolutely nothing. That’s why knowing the basics of good writing still matters, maybe now more than ever.

It’s Easy to Write. It’s Hard to Matter.

AI can give you perfectly structured sentences, throw in some industry buzzwords, and even match a tone. But that’s not enough.

Writing isn’t just about getting words on a page. It’s about making people care.

It’s about making the reader feel like this was written for me.

It should feel like, “Hey, this was written for me.”

That feeling is hard for AI to create. Because real connection needs a bit more, it needs intention, context, and a human who actually understands the audience.

So Why Do We Still Need to Learn Writing Basics?

Because tools don’t replace thinking.
Because content without intention is just noise.
Because the why behind your words matters just as much as the words themselves.

Before you (or an AI) write anything, ask yourself:

Why will this document exist?
What is it supposed to accomplish?
Who will be reading it?
What do they already know?
What do they need to know?
What tone is appropriate?
Why are they going to be reading it at all?

If you don’t have answers to these, the content has no compass.
And let’s be clear: If a document doesn’t have a purpose, it shouldn’t exist.

The Basics Still Matter, Even More Now

Let’s quickly revisit the basics, because yes, they still matter.

1. Know Your Audience
This is non-negotiable. AI can guess, but only you know who you're speaking to. Their pain points. Their language. Their habits.

2. Have a Purpose
What’s the job of this piece? Teach? Convince? Support? Don’t write for the sake of writing. Give every word a role.

3. Structure for Humans
Use headings. Short paragraphs. Bullet points. Respect the reader’s time and attention.

4. Write Like a Person
Drop the jargon. Be clear. Be honest. Add personality. People don’t connect with perfect, they connect with what feels honest and human.

5. Guide the AI, Don’t Let It Lead
Use AI to help you think, not replace thinking. Let it be your brainstorming partner, not your ghostwriter.

Final Thoughts: Clarity Is Still a Human Superpower

AI is here to stay, and that’s not a bad thing. It helps us write faster, cleaner, and sometimes even better.

But it can’t decide why a document should exist.
It can’t feel the frustration your audience feels.
It can’t speak with your voice.

So yes, let AI write the draft. But let you be the reason it matters.

Because today, everyone’s writing more, thanks to AI. But the content that stands out isn’t the longest or the most “perfect.”
It’s the one that’s clear.
It connects.
It knows its purpose.

And that part? It still starts with you.

✍️ Writing Better Error Messages: A Simple Guide Inspired by Google

Khaled Abdel-Fattah — Sun, 06 Apr 2025 10:34:49 +0000

Error messages are part of the user experience. When done right, they help users understand what's wrong and how to fix it. But when done poorly, they confuse users and frustrate developers.

Inspired by Google’s error message guidelines, this guide will help you write better, clearer error messages.

🔧 General Rules for Writing Good Error Messages

❌ Don’t Hide Errors

Always show a clear message when something fails. Silent failures are a big problem:

Users get confused.
Developers have no clue what went wrong from logs.

✅ Do this:

Couldn’t save your changes. Please check your internet connection and try again.

✅ Tell the User What Went Wrong

Be direct and specific. Avoid vague phrases like “Something went wrong.”

🚫 Don’t:

Error occurred.

✅ Do:

We couldn’t upload the file. The file format is not supported.

🧭 Help the User Fix It

An error message should tell users what they can do next.

🚫 Don’t:

Invalid input.

✅ Do:

Password must be at least 8 characters and include a number.

👤 Write for Humans, Not Machines

Avoid technical jargon or internal error codes in the message. Logs are for developers — messages are for users.

🚫 Don’t:

500: Internal Server Error – NullReferenceException

✅ Do:

Sorry, something went wrong on our side. Please refresh the page or try again later.

🔤 Use Simple and Friendly Language

Keep your language easy to understand. No need to sound robotic.

🚫 Don’t:

Access denied due to authentication failure.

✅ Do:

You need to sign in to view this page.

📱 Make Messages Clear on All Screens

Keep it short and meaningful — especially on mobile. Users might be reading it on small screens.

✅ Good:

No internet connection. Try again.

🧪 Bonus Tips

Don’t blame the user. Be polite and respectful.
Use consistent terms. If you say “sign in” in one place, don’t say “log in” elsewhere.
Don’t use “please” everywhere. Use it only when asking the user to do something.
Use humor only when it’s helpful. Never joke about data loss or serious errors.

✨ A Few Templates You Can Use

Situation	Message Example
Required field is empty	This field can’t be empty.
Invalid email format	Enter a valid email address.
Server error	Something went wrong. Try again later.
Action requires login	Please sign in to continue.
No internet connection	You’re offline. Check your connection.

🧵 Final Thoughts

A good error message doesn’t just explain what went wrong. It speaks like a human, not a robot.
It’s clear, helpful, and makes users feel supported, not stuck.
These small messages can make a big difference in how people experience your product.

Want to dive deeper? Check out the full guide by Google.

Your Guide to Better Documentation: Mastering Accuracy, Clarity, and Conciseness

Khaled Abdel-Fattah — Fri, 06 Dec 2024 21:28:31 +0000

We’ve come a long way through the Document Development Lifecycle (DDLC), from planning and research to writing and launching. Now, it’s time to wrap it up with some final thoughts on writing tips that can make your documentation more effective and engaging. Whether you're crafting a user guide, API reference, or internal documentation, accuracy, clarity, conciseness, and tone are essential to creating high-quality, user-friendly content.

In this blog, we’ll dive into practical writing tips that will help you improve your documentation and ensure it serves its purpose.

Writing Tips for Accuracy

When it comes to documentation, accuracy is everything. If the information isn’t correct, your users won’t be able to rely on it. Here’s how to ensure your content is accurate:

1. Consult with Subject Matter Experts (SMEs)

It’s important to get input from those who know the subject inside and out. Subject Matter Experts (SMEs) are the ones who can confirm technical details, verify information, and make sure you're on the right track.

Reach out to SMEs regularly: They can clarify concepts, review your content, and suggest improvements.
Cross-check facts: Always double-check the information you include, especially when dealing with technical topics, to ensure everything is accurate.

2. Conduct Usability Testing

Test your documentation by letting users try it out. Real-world testing helps identify gaps, confusing sections, or unclear instructions. You can get feedback through:

Surveys or feedback forms from users who have interacted with the docs.
User interviews to hear their thoughts on how the documentation could be improved.

3. Proofread Thoroughly

It may seem obvious, but proofreading your document is one of the most important steps to ensure accuracy. Even small typos or errors can undermine your credibility.

Take breaks between writing and proofreading: This helps you see your document from a fresh perspective.
Use tools like Grammarly to catch grammatical errors, but don’t rely on them entirely—human eyes are still the best at catching mistakes.

Writing Tips for Clarity

The clearer your document, the easier it will be for your readers to understand and use. Here’s how to ensure your documentation is as clear as possible:

1. Use Clear Structural Elements

Your document should be easy to navigate. Good structure makes a huge difference:

Table of Contents: Helps readers find what they need quickly.
Headings and Subheadings: Breaks down large sections into manageable chunks.
Lists and bullet points: Makes information digestible.

2. Remove Ambiguity

Avoid vague language or terms that could confuse the reader. Be precise with your wording and make sure every instruction or explanation is clear.

Avoid jargon or unclear terms: If you need to use technical terms, explain them.
Use active voice: Active voice makes sentences easier to read and more direct.

3. Use Visuals to Enhance Understanding

A picture is worth a thousand words—especially when it comes to documentation. Visuals can help clarify complex concepts or instructions.

Screenshots: Capture what the user should be seeing at each step. Make sure to add annotations where necessary to highlight important details.
Flowcharts: These are useful for showing processes or workflows.
Graphics Tools: Tools like Draw.io, Excalidraw, Carbon, FigJam, and Lucidchart can help you create clean, easy-to-understand visuals.

4. Place Visuals Near the Relevant Text

Place visuals as close as possible to the sections they explain. This helps the reader understand the context and follow along with the steps.

Tip: For even more dynamic documentation, consider using Flow Animations at Draw.io to visually demonstrate actions or flows, Learn how.

Writing Tips for Conciseness

No one wants to read a lengthy document full of unnecessary fluff. Here's how to keep your writing concise and to the point:

1. Convey Only What’s Needed

Stick to the essentials. Don’t overload your readers with information they don’t need.

Remove repetition: Say it once, and say it well.
The best sentence is the shortest: Keep your sentences clear, direct, and to the point.

2. Avoid Unnecessary Corporate Jargon

Corporate jargon may sound formal, but it can confuse readers, especially if they aren’t familiar with your company’s internal terms. Keep it simple, and be direct.

Writing Tips for Tone

The tone of your documentation sets the mood and helps users feel more comfortable using it. It’s crucial to match your tone to your audience and the purpose of your document.

1. Adapt to Your Audience

While developers may be your primary audience, your documentation may be used by others—like product managers, business teams, or non-technical users. Be mindful of this:

Tailor your tone to fit the audience’s expertise level.
For developers, you can use more technical language, but for non-technical readers, keep it simple and explanatory.

2. Be Personable and Approachable

Documentation doesn’t need to be robotic or dry. Show some personality! A friendly and approachable tone helps users feel comfortable, especially in complex or stressful situations.

Show empathy: Acknowledge potential frustrations that users might encounter.
Be encouraging: Help users feel confident that they can achieve the task at hand.

Wrapping It All Up

Writing effective documentation isn’t just about putting words on a page; it’s about crafting clear, accurate, and concise content that makes the user’s experience smoother. By focusing on accuracy, clarity, conciseness, and tone, you can create documentation that’s not only helpful but also engaging.

Whether you’re writing guides, API docs, or knowledge bases, these tips will help you get your message across and make sure your users find what they need.

What’s Your Approach to Writing Documentation?

Do you have any other writing tips that have worked for you? How do you ensure your documentation is clear, concise, and helpful? Share your thoughts in the comments!

Your Guide to Better Documentation: Launching Your Docs with Confidence

Khaled Abdel-Fattah — Fri, 06 Dec 2024 21:17:25 +0000

After all the planning, researching, writing, and editing, it’s finally time to hit "publish" and share your documentation with the world! The Launch Phase is the final step in the Document Development Lifecycle (DDLC), and while it might seem like the end, it’s actually just the beginning of keeping your documentation up-to-date and relevant.

In this blog, we’ll cover everything you need to know to launch your documentation successfully and ensure it stays useful as your software or product evolves.

Why the Launch Phase Matters

Launching your documentation is not just about making it available to your audience—it's about ensuring they can find and use it effectively. Think of the Launch Phase as the moment you open the doors to your work. Once it's out there, it’s up to you and your team to keep it alive and aligned with changes to your software or product.

As you prepare to launch, keep this in mind: documentation is a living, breathing thing. Just like software, it needs regular updates and maintenance to stay accurate and useful.

1. Get the Timing Right

Timing is key when launching your docs. If you wait too long to release them, the information may already be outdated. If you launch too soon, you might miss critical updates.

Here’s what to do:

Coordinate with the release cycle: If your documentation is tied to a software release, make sure everything is aligned. The launch of the docs should happen around the same time as the software release or update.
Preview your docs: Before going public, preview your documentation with a small group of internal users to catch any gaps or mistakes.

2. Make It Accessible

The success of your launch depends on how easily your audience can access the documentation. Here are some tips to make sure your docs are easy to find and navigate:

Choose the right platform: Host your documentation where users can easily access it. This could be a dedicated website, a knowledge base, or even directly within the software application itself.
Organize for ease of use: Ensure your documentation is well-organized, with clear headings, navigation menus, and search functionality.
Promote it: Share the launch with your audience. Post about it on social media, include a link in newsletters, or even host a webinar or training session to walk users through the new docs.

3. Track Feedback and Usage

Once your docs are live, it’s important to keep track of how they’re being used and what feedback you’re getting from your users. Here’s how to stay on top of this:

Monitor usage metrics: Use tools like Google Analytics or built-in analytics from your documentation platform to see which sections are being visited most often and where users are spending their time.
Request feedback: Actively encourage users to give feedback on your documentation. Include a feedback form or a contact email where users can report problems or suggest improvements.
Engage with your users: If someone leaves feedback or asks a question, respond quickly. This shows that you’re invested in improving the documentation and makes users feel heard.

4. Keep It Updated

As your product or software evolves, so too must your documentation. This is where the living document concept comes into play. A document that’s accurate today might not be useful tomorrow if it’s not regularly updated to reflect new features, changes, or bug fixes.

Here’s how to manage updates:

Establish a process for updates: Make sure you and your team have a clear process in place to update documentation as changes happen. If new features are added or functionality changes, your docs need to reflect that in real-time.
Assign ownership: Designate a person or team responsible for keeping the documentation up-to-date. This ensures that the task doesn’t get forgotten or neglected.
Create a version control system: If your product evolves rapidly, version control for documentation might be helpful. This ensures that users can still access the right documentation for the version of the software they’re using.

5. Celebrate the Launch!

Once your documentation is live, take a moment to celebrate! You’ve worked hard to get it to this point, and now it’s out there to help users. Share the good news with your team and stakeholders, and appreciate the work that went into making the docs successful.

Final Thoughts

The Launch Phase is the last step in creating your documentation, but it’s by no means the end. Just like with your product, documentation is an ongoing project that needs constant attention to stay relevant and helpful.

Once your docs are live, stay proactive by tracking feedback, monitoring usage, and keeping things updated. The more effort you put into maintaining your docs, the more value they’ll provide to your users over time.

Ready to Launch Your Docs?

How do you approach the Launch Phase in your documentation process? Do you have any tips or tools that help make the launch smoother? Share your thoughts in the comments!

Your Guide to Better Documentation: Perfecting Your Content in the Review & Edit Phase

Khaled Abdel-Fattah — Fri, 06 Dec 2024 21:14:06 +0000

We’ve all been there—writing a document, feeling like it’s ready to go, only to realize after a break that it could use some more work. That’s where the Review and Edit Phase comes in. This is the final step in turning your first draft into something polished, clear, and easy for your audience to understand.

In this blog, we’ll walk you through the importance of reviewing and editing your document, plus some helpful tips and tools to make the process smoother.

Why the Review & Edit Phase Matters

The Review and Edit Phase is all about fine-tuning your content. You’ve done the hard work of gathering information and writing it down, but now it’s time to make sure it’s organized properly, flows smoothly, and is as clear as possible for the reader. This phase ensures that your document is both effective and professional.

Tips for the Review & Edit Phase

1. Adjust and Reorganize Content

Even if your first draft looks good, there might be areas where the structure or flow could be improved. Look at your content with fresh eyes and ask yourself:

Does the document make sense overall?
Are there sections that are out of order or need to be restructured?
Is the information presented in a way that’s easy for the reader to follow?

You might find that rearranging a few paragraphs or sections helps improve the clarity and flow.

2. Edit for Style

Style refers to how your content reads—not just the information you’re presenting, but how it comes across. Is the tone appropriate for your audience? Is the writing consistent throughout?

Here’s what to check during your style edit:

Voice and tone: Ensure that the document sounds natural and fits your audience. For example, if it’s a user guide, the tone should be friendly and approachable, but professional.
Consistency: Is your tone, terminology, and formatting consistent? Make sure the document reads as a cohesive whole.
Clarity: Look at every sentence and ask, “Is this as simple and clear as it can be?” Cut out unnecessary words and phrases.

3. Edit for Grammar and Punctuation

The technicalities of grammar and punctuation might seem like small details, but they matter! Even a well-written document can lose credibility if it’s riddled with errors. Make sure to:

Fix any spelling, grammar, and punctuation mistakes.
Watch for common errors like comma splices, run-on sentences, or improper subject-verb agreement.
Pay attention to formatting, such as headings, lists, and bullet points. These small details make a big difference in readability.

4. Get a Fresh Set of Eyes

Sometimes, the best way to spot issues is to let someone else review your document. After working on it for a while, it’s easy to miss things that might be unclear or awkward.

Here’s what you can do:

Ask a colleague to review it: Have someone who wasn’t involved in the creation process read through the document. They’ll spot things you might have overlooked and give you valuable feedback.
Take a break: If possible, step away from the document for a little while before reviewing it. Coming back to it with fresh eyes will help you spot errors and areas that need improvement.
Read out loud: Reading your document out loud forces you to slow down and catch awkward phrasing, missing words, or areas where the content doesn’t flow well.

5. Edit with a Knife

This might sound harsh, but it’s a good rule of thumb: if something doesn’t add value, cut it out. Every word in your document should serve a purpose. If you find sections that feel redundant or aren’t necessary to the main point, don’t be afraid to remove them.

Being ruthless about editing helps you keep the content concise and focused, making it easier for the reader to understand and follow.

🚨 It’s an Iterative Process

Keep in mind that the Review and Edit Phase is rarely a one-and-done deal. In most cases, the process is iterative. After one round of edits, you’ll probably find that you need to review and adjust again. And that’s okay!

Don’t rush this phase. Take your time to review your document multiple times, and make improvements along the way. This is where the document becomes truly polished.

Tools That Can Help

The right tools can make editing easier and more efficient. Here are a few that can help you through the process:

Grammarly: An AI-powered tool that helps catch grammar, spelling, and punctuation mistakes, and even suggests improvements for clarity and tone.
ChatGPT: You can use ChatGPT to help rephrase sentences, suggest better wording, or even provide content ideas.
Confluence (Page Approval): If you’re working with a team, Confluence’s page approval features allow you to collaborate on document revisions and get feedback directly within the tool.

Wrapping Up

The Review and Edit Phase is essential for ensuring your documentation is clear, accurate, and easy to understand. It’s not just about fixing grammar mistakes—it’s about making sure your content flows well, serves its purpose, and is tailored to your audience’s needs.

Take your time during this phase, get feedback, and keep refining your work. Once you’re happy with the result, you’ll be ready to move on to the final phase—Launching Your Document—and share your valuable content with the world.

How Do You Approach the Review and Edit Process?

What’s your strategy for reviewing and editing your documentation? Do you have any tips or tools that help you perfect your content? Share your thoughts in the comments!

Your Guide to Better Documentation: Writing Your First Draft and Beyond

Khaled Abdel-Fattah — Fri, 06 Dec 2024 21:08:50 +0000

By now, you've gathered your research, organized your thoughts, and outlined your goals. It's time to put pen to paper—or fingers to keyboard—and start writing! The Writing Phase is where the magic happens. It's the phase where your planning, research, and ideas come together into something real and usable.

In this blog, we’re going to talk through the steps of writing your documentation, from organizing your ideas to reviewing and revising your first draft. It might sound like a simple process, but when you’re crafting documentation, there’s a lot more to consider than just putting words on a page.

1. Organize Your Ideas Before You Start

Before you dive into writing, take a step back and think about the structure of your document. You don’t want to start writing and realize halfway through that you missed a key point or the flow doesn’t make sense. Organizing your content ensures that your document stays clear and easy to follow.

Here’s how to organize your ideas:

Outline your sections: Break down the document into sections or chapters. What are the main topics you need to cover? What order will make the most sense for the reader?
Create a flow: Think about how each section connects to the next. Does the document follow a logical progression? Will the reader be able to easily find the information they need?
Use headings and subheadings: These guide the reader through the content and make it easier to scan. Keep them short and to the point.

2. Does the Document Fulfill Its Purpose?

As you start writing, keep checking back to your original goals and purpose. You don’t want to wander off track. Ask yourself:

Does the document fulfill its purpose? If you set out to help users solve a problem or learn something new, does the document actually achieve that?
Is anything missing? Sometimes, you’ll realize you didn’t cover something crucial during the research phase. Add it in before you get too far along.
Can anything be taken out? On the flip side, make sure you haven’t included unnecessary information. Keep it simple and to the point.
What questions will the reader have? Try to anticipate questions or confusions the reader might encounter. Include answers or explanations to make it easier for them to follow.
Is the writing easy to understand? Avoid jargon unless absolutely necessary. Your goal is clarity, not complexity.

3. Write the First Draft

Now that you’ve organized your thoughts and checked your goals, it’s time to write the first draft. The first draft is your chance to get everything down, so don’t worry about perfection. The focus is on content, not style.

Here’s a simple approach for writing your first draft:

Don’t overthink it: Just get the ideas out. It doesn’t need to be polished yet.
Keep it simple: Use clear, direct language. Write as if you’re explaining something to a friend who doesn’t know the topic.
Stay focused: Stick to the main points. Don’t go off on tangents or include irrelevant details.
Write in your own voice: While the tone may vary depending on the audience, make sure the document sounds human and approachable.

4. Review and Revise

Once the first draft is done, it’s time to step back and review. This is where the real magic happens. The writing phase isn’t complete until you’ve carefully reviewed your content, made revisions, and polished it for clarity and flow.

Here are some tips for reviewing and revising:

Read it out loud: Sometimes, hearing your content helps you spot awkward phrasing or unclear sections.
Check for clarity: Is everything easy to understand? If something doesn’t make sense, rewrite it. It’s okay to get feedback from others too.
Fix the structure: Is there a logical flow to your document? Make sure the reader can easily navigate through it.
Focus on readability: Use short sentences and paragraphs. Bullet points, numbered lists, and visuals can break up dense sections and make it easier to digest.
Check for consistency: Make sure you’re consistent with terminology, tone, and formatting throughout the document.

5. Iterate, Improve, and Refine

The first draft is just that—a draft. Don’t be afraid to iterate and improve it. Keep refining it until it achieves the clarity and purpose you set out with. This might mean multiple rounds of revision, and that’s okay. Good documentation doesn’t happen overnight, but with each revision, you’ll get closer to creating something really helpful for your audience.

Final Thoughts

The Writing Phase is where everything comes together. It’s about taking all your research, organizing it into a logical structure, and putting it into words in a way that’s clear and accessible for your audience.

Remember, don’t aim for perfection on your first draft—just aim to get your ideas down. From there, it’s all about refining and improving. By the end of this phase, you’ll have a document that not only meets its purpose but is easy for your audience to understand and use.

In the next blog, we’ll discuss the Review and Edit Phase, where we’ll go into the finer details of finalizing your document and making sure it’s as polished and professional as possible.

How Do You Approach Writing Documentation?

How do you handle the writing phase in your documentation process? Do you have any tips for writing clear and effective content? Share your thoughts in the comments!

Your Guide to Better Documentation: How to Get the Right Information During the Research Phase

Khaled Abdel-Fattah — Fri, 06 Dec 2024 21:03:27 +0000

You’ve got a clear purpose for your document, and you know who your audience is. Now, it’s time to gather the information that will make your documentation both useful and accurate. This is where the Research Phase comes in—a crucial step that shapes everything you write.

In this blog, we’ll dive into how to collect the right information, why it’s important to get insights from developers and users, and how to interview subject matter experts (SMEs) to create clear and practical documentation.

Why the Research Phase Matters

At its core, the Research Phase is about taking information from the heads of the creators—like developers or product managers—and translating it into something users can actually understand and use.

Good documentation doesn’t just come from what you know—it comes from what your audience needs to know. This phase ensures that you’re building your content on a strong foundation of accurate, relevant information. Without it, your document will miss key details or get too technical, leaving users confused.

Here are some essential ways to gather information:

1. Interview Subject Matter Experts (SMEs)

The first and most obvious place to start is with the people who know the product or service best: the subject matter experts. Whether it’s developers, product managers, or support staff, SMEs have the deep knowledge that your document needs. But how do you extract that knowledge?

Here are some tips for effective interviews:

Prepare your questions: Don’t just ask, “What does this do?” Break things down into specific use cases, problems, and scenarios.
Ask "Why?": Understanding the reasoning behind features or processes helps you explain them clearly.
Get into the details: Don’t be afraid to dive deep into technical explanations, even if they seem complex. You can simplify these later for your audience.

The goal here is to understand the ins and outs of the product or service, and capture that knowledge in a way that’s easy to communicate.

2. Review Existing Documentation

Before reinventing the wheel, take a look at what’s already been documented. Review any existing guides, release notes, FAQs, or internal documents. You might find that some information is already available, which can save time and effort. Plus, you can see what’s working and what’s not.

Here are a few things to keep in mind while reviewing existing docs:

Consistency: Make sure the voice, tone, and style align with what you want for your document.
Gaps: Identify missing or outdated information that your new document can fill in.
User feedback: Look at any comments, support tickets, or forums where users have expressed confusion or asked questions about existing docs. This can give you clues on what needs more clarification.

3. Use and Test the Software (or Tool)

Nothing beats hands-on experience. If possible, try out the software or tool you’re documenting. Testing it yourself will help you understand the user experience, spot potential issues, and find out what works well and what doesn’t.

Follow real user workflows: Put yourself in the shoes of the end user. Go through the process from start to finish as they would. This helps you see the product from their perspective.
Take notes: While testing, jot down things that confuse you, areas where you get stuck, or features that could use more explanation. These insights will be crucial for making your documentation clearer and more effective.
Talk to users: If you can, get feedback from actual users about their experience with the product. Their pain points and questions will give you a clear direction for your document.

4. Research Competitor or Similar Documentation

It’s also helpful to look at how others have tackled similar documentation. How do other companies or products explain features that are similar to yours? What works well in their documentation? What could be improved?

Here are some things to look for when reviewing competitors’ docs:

Clear Structure: How is the information organized? Is it easy to follow?
Tone and Voice: Is it professional, friendly, or casual? Does it fit the audience?
Examples and Visuals: Do they include helpful screenshots, diagrams, or videos? These can make documentation much more understandable.

Don’t copy—learn from their best practices and adapt them to fit your needs.

5. Involve Developers Early

While interviewing SMEs is essential, it’s also important to keep developers in the loop. In the process of research, you’ll likely uncover questions or ideas that need technical clarification. Keeping developers involved early ensures that the technical details are accurate and easy to explain.

Here’s how to make the most of working with developers during research:

Have them review your drafts: Once you’ve gathered your information, have a developer review your content to ensure accuracy.
Collaborate on difficult topics: Some topics may be tricky to explain in simple terms. Work with developers to find ways to simplify complex explanations without losing meaning.

Tips for Effective Research

Here are a few bonus tips to keep in mind during the research phase:

Stay Organized: With so much information coming from different sources, it’s easy to get overwhelmed. Keep your notes, interviews, and documents organized for quick reference.
Keep the Audience in Mind: Throughout your research, always ask yourself, “How does this help the user?” Remember, you’re translating technical knowledge into usable content for your audience.
Ask Follow-Up Questions: Don’t be afraid to go back to SMEs or developers with new questions if something doesn’t make sense. The more you understand, the better your documentation will be.

Wrapping Up

The Research Phase is your chance to gather all the details and insights that will shape your documentation. It’s where you dig deep into the product, talk to the people who know it best, and make sure your content will actually help users.

In the next blog, we’ll dive into the Write Phase, where you’ll start turning all your research and planning into clear, usable documentation.

What’s Your Research Process?

How do you gather information for your documentation? Do you have any tips for interviewing SMEs or testing the software? Share your thoughts in the comments—I’d love to hear how you approach this critical phase!

Forem: Khaled Abdel-Fattah

For Muslims: Stay Consistent With Salah at Work Using This Slack App

Why a Prayer Reminder Inside Slack?

Pre-Adhan Reminders: Prepare Before Prayer Time

🤝 Join Jama’ah: Find Colleagues to Pray Together

🕌 Set Status: Praying

Accurate, Location-Based Prayer Times

Install Muslim Prayer Reminder for Slack

Writing Docs in a World Where LLMs Are the Readers

1. How Google Cloud Is Adapting Documentation for AI

2. Documentation Is No Longer Read Only by Humans

3. Tech Writers Do Not Compete With AI. They Enable It.

4. What llms.txt Is and What It Is Not

5. Make llms.txt Auto-Generated

6. Lessons from Google Cloud’s AI Code Systems

7. How to Use llms.txt in Practice

8. Make It Easy to Find

Muslim Prayer Reminder for Slack

Why a Prayer Reminder in Slack?

What the App Does

Automatic Prayer Reminders

Location-Based Prayer Times

Custom Settings

How It Works

A Simple Reminder of What Matters

Should I Be Proud If I Didn’t Really Work for It?

Too Many Em Dashes, Not Enough Sense

In the Age of AI, Why Bother Learning to Write?

It’s Easy to Write. It’s Hard to Matter.

So Why Do We Still Need to Learn Writing Basics?

The Basics Still Matter, Even More Now

Final Thoughts: Clarity Is Still a Human Superpower

✍️ Writing Better Error Messages: A Simple Guide Inspired by Google

🔧 General Rules for Writing Good Error Messages

❌ Don’t Hide Errors

✅ Tell the User What Went Wrong

🧭 Help the User Fix It

👤 Write for Humans, Not Machines

🔤 Use Simple and Friendly Language

📱 Make Messages Clear on All Screens

🧪 Bonus Tips

✨ A Few Templates You Can Use

🧵 Final Thoughts

Your Guide to Better Documentation: Mastering Accuracy, Clarity, and Conciseness

Writing Tips for Accuracy

1. Consult with Subject Matter Experts (SMEs)

2. Conduct Usability Testing

3. Proofread Thoroughly

Writing Tips for Clarity

1. Use Clear Structural Elements

2. Remove Ambiguity

3. Use Visuals to Enhance Understanding

4. Place Visuals Near the Relevant Text

Writing Tips for Conciseness

1. Convey Only What’s Needed

2. Avoid Unnecessary Corporate Jargon

Writing Tips for Tone

1. Adapt to Your Audience

2. Be Personable and Approachable

Wrapping It All Up

What’s Your Approach to Writing Documentation?

Your Guide to Better Documentation: Launching Your Docs with Confidence

Why the Launch Phase Matters

1. Get the Timing Right

2. Make It Accessible

3. Track Feedback and Usage

4. Keep It Updated

5. Celebrate the Launch!

Final Thoughts

Ready to Launch Your Docs?

Your Guide to Better Documentation: Perfecting Your Content in the Review & Edit Phase

Why the Review & Edit Phase Matters

Tips for the Review & Edit Phase

1. Adjust and Reorganize Content

2. Edit for Style

3. Edit for Grammar and Punctuation

4. Get a Fresh Set of Eyes

5. Edit with a Knife

🚨 It’s an Iterative Process

Tools That Can Help

4. What `llms.txt` Is and What It Is Not

5. Make `llms.txt` Auto-Generated

7. How to Use `llms.txt` in Practice