My Frequently Asked Questions (FAQ)

How Did You Become a Technical Writer?

Like many technical writers, I sort of fell into it. I discovered that technical writing was a lucrative profession for technical people who came to Israel from the English-speaking world. I had a technical background and enrolled in a technical writing course at a very good time (1995) considering the proliferation and success of high-tech companies in the country. I must admit it was an adjustment after previously working in the laboratory or in production, but the excellent conditions that a high-tech company could offer helped me to quickly acclimatise to an office environment.

How Do You Gather Information for Your Documentation?

In the age of Artificial Intelligence (AI), I no longer expect Subject Matter Experts (SMEs) to hand me anything but raw content through Jira, Confluence, etc. I operate on an investigator mindset and a "Draft as Discovery" methodology. I use AI tools to scrape the developers' codebase, engineering specs, Jira tickets, Confluence, SharePoint, etc., to build a first draft. I then use that draft as a starting point to interview the developers and SMEs, using their time efficiently to fill in specific technical gaps rather than starting from scratch.

Is AI Going to Replace Technical Writers?

AI is a powerful writing assistant for efficiency, not a replacement for technical writers. I use AI tools to help automate documentation maintenance and troubleshooting tasks, generate first drafts, and check code snippets. However, all technical verification, developer and SME interviewing, conceptual architecture explanations, and final editing are done entirely by me to ensure 100% accuracy and style alignment.

How Do You Choose a Documentation Tool?

If you are joining an established company, you will have to work with the tool they use to generate the documentation (at least at the start). If you have never worked with that specific tool, there is a learning curve to surmount. With experience, you'll learn new tools faster. In start-ups with minimal existing documentation, you often get to decide which tool to go with. In larger companies you may get the chance to migrate the existing documentation to a more efficient tool. Either way, you need to present two or three viable alternatives to management, evaluate the advantages and disadvantages of each, and then recommend the one that best meets your requirements.

The decision should take the following into account:

• Budget: Whatever you decide, the price of the tool and licenses will have to be within the budget for the department. If the price is way beyond budget, you could try to get other stakeholders to buy into your idea by proposing that they could benefit too. You should reach out to Customer Support. If a more efficient documentation platform could save the company money on support calls, or can integrate with Salesforce or Zendesk, they might be interested in participating in the purchase. ROI (Return on Investment) is not easy to estimate for documentation. Look for different angles. For example, a platform that delivers instant documentation updates is better than one that does not.

• AI Compatibility: Now essential. You absolutely need to confirm that the content can be structured and optimized for AI with a Proof of Concept (POC).

• Vendor lock-in: If possible, select a tool that lets you write to an open-source standard, such as XML or DITA, or community-driven such as Markdown, so that your source content is portable.

• Company Security Policy: Adopting a new tool requires passing a security compliance review. Who makes the final decision depends entirely on the size and structure of your organization, but it typically falls on specific leadership roles and specialized teams.

  • CISO (Chief Information Security Officer): In medium-to-large organizations.
  • CIO / CTO (Chief Information or Technology Officer): If there isn't a dedicated CISO.
  • Head of IT / Operations: In smaller companies or startups.

• Collaboration with non-writers: For collaboration with developers and other functions, the closer you can get to work with them, the better. Developers trust writers who use the same tools they do. Moving your documentation to a GitHub repository is a great example. You push and pull just like they do.

  • Consider how you will provide content for your reviewers. They will need easy access and a user-friendly editing environment. Also check if the tool has an internal reviewing feature. The catch is that you may need an extra license per (non-writer) reviewer. These built-in review workflows are usually designed for peer reviews rather than external reviews.
  • Find out whether the tool smoothly integrates with the company's task-based applications such as Jira, GitHub for version-control, etc.

• Collaboration Between Technical Writers: Even if you're the sole technical writer in a start-up, you need to prepare for the day when you will need additional writers, whether in-house or outsourced. Many tools allow a local client installation for each writer, though others keep everything on the server side.

• If your documentation contains a lot of repeated (reusable content) or needs to be single-sourced for multiple products in a product line, select a tool that enables this functionality Out-Of-The-Box (OOTB).

• Evaluation and Results: You will need to evaluate each tool with a POC in an environment that simulates the actual company environment. Create a test plan for all the basic features, any other features that are important to the team, and test scenarios where several writers are working in parallel. Request that each member of the team go through the test plan and evaluate their experience. Be aware that the editing interface may be a key factor here. After all, writers are averse to an interface that is not perceived as user-friendly.

Can You Work in a Docs-as-Code Workflow Environment?

Yes. I am fully integrated into modern Docs-as-Code workflows. I routinely work with Markdown/MDX, static site generators like Docusaurus, version control through GitHub, and environments like Visual Studio Code. I can open PRs, handle markdown formatting, and collaborate directly inside a repository.

How Do You Deal With Uncooperative Developers?

To be honest, I haven't come across many uncooperative coworkers from other departments. I make sure to prepare for any meeting I set up. I do my homework and write down the questions I want to ask. I research the terminology involved in the feature or concept. I want the person I am interviewing to know that they do not have to explain everything from scratch. If my requests for a meeting are continually denied, I will escalate the issue.

How Do You Make Your Documentation AI-Ready?

When technical documentation is ingested by Large Language Models (LLMs) or deployed inside Retrieval-Augmented Generation (RAG) pipelines, its structural composition determines the accuracy of AI-generated answers.

Here are some guidelines to help make your documentation AI-ready:

• Front Matter Token Metadata: A structured metadata block, normally at the top of a topic should provide explicit keys, for example, (core_concepts, audience, description). When parsed by custom documentation parsers or vector database indexers, these parameters act as high-weight anchors. They guarantee that an AI agent filtering by metadata can match the user's explicit intent immediately, filtering out neighboring topics and preventing keyword drift.

• Strict Noun Anchoring (Pronoun Mitigation): Standard technical documentation often defaults to ambiguous context pronouns such as "it", "this", or "the system". In contrast, an AI-ready topic maintains strict entity naming consistency across sentence boundaries. For example:

• Sub-optimal: "Extract its value and hash it with your secret."

• AI-Optimized: "Hash the concatenated signature payload using the HMAC-SHA256 algorithm, utilizing your WEBHOOK_SECRET..."

• Symmetric Structural Mirroring: Match your procedural steps to code comments. Use identical numbering and terminology (// 1. Extract values → Extract, etc.) so AI agents can map steps directly to code lines.

• Semantic Formatting Isolation (Markdown Example): Using strict Markdown standards—such as explicit backticks for variables (WEBHOOK_SECRET), bolding for strict UI actions (Reveal Secret), and native alert blocks (> [!WARNING])—allows regex-based parsing scripts and LLM tokens to instantly distinguish operational mechanics from ordinary conceptual descriptions. Other platforms like DITA or AsciiDoc have similar semantic isolation features.