A freelance technical writer needs a stack that can inspect source material, author structured content, validate code and links, manage client review, track scope, and protect confidential information. AI is useful for transformation and gap detection; it is unreliable as the source of product behavior. The leanest stack changes with the client’s publishing system, so standardize the workflow rather than forcing every client into one tool.
The core stack
| Need | Practical choice | Upgrade when needed | Main caution |
|---|---|---|---|
| Source and code | GitHub plus VS Code | GitLab, Bitbucket, client VDI | Access and secrets must be isolated by client |
| Authoring | Markdown, Vale, Git | MadCap Flare or Paligo for structured multi-channel content | A CCMS adds cost and administration |
| API documentation | OpenAPI, Redocly, Stoplight | ReadMe or developer portal platform | Schema and implementation can diverge |
| AI assistance | Claude, ChatGPT, or GitHub Copilot | Enterprise workspace with contractual controls | Never upload client material to an unapproved account |
| Review | Pull requests or Google Docs | Frame.io-style review is unnecessary for most docs; use the client’s issue system | Parallel comments can create competing versions |
| Business operations | Harvest or Toggl Track, Bonsai or QuickBooks | Accountant-managed system | Time tracking does not replace scope control |
Keep each client in a separate security boundary
Use a dedicated password-manager vault, browser profile, repository folder, and communication channel for every client. Prefer client-provided single sign-on and accounts. Do not forward proprietary files to a personal mailbox or synchronize them into an unapproved consumer cloud.
Record the contract’s confidentiality, data-location, AI, subcontractor, retention, and portfolio-display terms. “May use AI” is not specific enough; identify approved vendors and data classes. Source code, unreleased roadmaps, support tickets, credentials, security findings, personal data, and customer contracts may require different treatment.
Enable full-disk encryption, multifactor authentication, automatic updates, device lock, encrypted backup, and remote-wipe capability. Keep secrets in a password manager or environment system, never in notes or prompt history. At project end, return or delete material according to the agreement and retain only records legally required for tax and business administration.
Author docs as code when the product is code
Markdown in the same repository as the software gives engineers familiar review, history, branches, and CI. VS Code supports Markdown preview and extensions; GitHub pull requests keep comments attached to exact changes. Static-site tools such as Docusaurus, MkDocs, Sphinx, Astro Starlight, and Hugo serve different ecosystems. Follow the client’s existing platform unless migration is part of the paid scope.
Install Vale for style linting and configure rules for terminology, sentence patterns, inclusive language, and prohibited claims. Add markdownlint, a link checker, spell checking, and the documentation build to CI. Lint rules should catch repeatable problems, not police every stylistic choice. Put the glossary and style configuration under version control.
Ask GitHub Copilot or an approved LLM to explain a selected symbol, propose a docstring, identify undocumented configuration, or convert verified notes into a tutorial outline. Require file and symbol references. Open the implementation and tests; generated explanations commonly miss feature flags, defaults, error paths, or version differences.
Use structured authoring only when reuse justifies it
MadCap Flare is strong for single-sourcing content across web help, PDF, knowledge bases, and other outputs, with variables, conditions, snippets, and mature publishing. Flare Online adds cloud collaboration and AI-assisted functions. Paligo is a cloud component-content-management system built around structured reuse and multi-channel publishing. Both suit product families, localization, variants, and regulated content better than loose documents.
They are expensive and require information architecture. Check current quotes for authors, reviewers, translation workflows, publishing, storage, and support. A freelancer should not buy an enterprise CCMS speculatively; work through the client’s license or include tooling in the proposal.
Before creating reusable components, calculate the maintenance benefit. A warning used in 18 manuals should be a controlled component. A two-sentence introduction appearing twice may be easier to duplicate than to condition. Excessive reuse creates fragments that are hard to read and risky to change.
Treat API documentation as an executable contract
Start with an OpenAPI document when documenting REST APIs. Inspect route code, validation, authentication, serializers, examples, and integration tests. Redocly CLI or Spectral can lint the schema; Stoplight provides collaborative design and documentation; ReadMe offers a hosted developer hub and interactive features. Pricing and included projects differ, so check current plans.
Test every request example against a safe environment. Use placeholders for tokens and IDs, state the base URL and version, and document success plus representative errors. Validate pagination, idempotency, rate limits, retries, time zones, units, nullability, and deprecation. Never copy a production response containing customer data.
For SDK docs, pin the package version and run examples in a clean environment. A code block that compiled six months ago can fail after a renamed method. Automate sample execution where practical.
Capture expert knowledge efficiently
Send subject-matter experts a focused pre-read: intended reader, questions, known sources, and decisions required. Record only with permission using the client’s approved Zoom, Teams, Grain, Fathom, or transcript system. Mark confidential segments and verify quotations.
During the interview, demonstrate the workflow. Ask the engineer to start from a clean account and narrate prerequisites, permissions, failure states, and recovery. Screenshots and transcripts are evidence, but product behavior and approved specifications govern.
Use AI to cluster transcript topics, identify unanswered questions, and generate a candidate task sequence. Do not ask it to fill missing answers. Maintain a source ledger linking each consequential claim to a test, specification, ticket, or named reviewer.
Run one review channel
Choose pull requests for docs-as-code and Google Docs or Word with tracked changes for narrative material. Do not accept simultaneous edits in a PDF, chat, email, and repository. Name one client approver who resolves conflicting feedback.
Separate reviews: technical accuracy, editorial quality, legal or security, and final release. Asking everyone to review everything creates delay and contradictory preferences. Put deadlines and acceptance criteria in the project plan. Silence is not approval unless the contract explicitly says so.
For screenshots, specify product version, account type, viewport, theme, language, and redaction. Keep editable source and use a naming convention tied to the page. Blur is not always safe redaction because underlying pixels or metadata may survive; use opaque replacement and flatten a reviewed export.
Use AI for controlled transformations
Good tasks include producing an outline from verified notes, rewriting a paragraph for a defined reading level, generating alternative headings, translating an approved glossary-aware draft for professional review, creating test cases for code samples, and comparing a release diff with current documentation.
Poor tasks include inventing a tutorial for an unavailable product, writing security guidance from general knowledge, summarizing an entire private repository in a consumer account, or generating citations. Treat every model output as untrusted until verified. Keep prompts and outputs when the client requires auditability, and delete them according to retention terms.
Price and manage the freelance work
Use fixed fees when deliverables and review rounds are defined; use day or hourly rates for discovery, embedded work, and unstable scope. The statement of work should list pages or artifacts, source readiness, client responsibilities, review rounds, meeting allowance, accessibility, screenshots, code testing, publishing, and out-of-scope changes.
Harvest and Toggl Track are straightforward for time and budget visibility. Bonsai combines proposals, contracts, time, and invoicing for freelancers, while QuickBooks or Xero may fit accounting requirements. Check current prices and local tax support. Track time by discovery, drafting, validation, review, and administration so future estimates improve.
Invoice against milestones and use change requests when the product or audience changes. Include a kill fee or cancellation terms. Maintain professional liability and cyber coverage where appropriate, and never promise legal compliance unless qualified to assess it.
Verdict and practical recommendation
For most software clients, the essential stack is VS Code, Markdown, GitHub, Vale, a documentation-site generator, an approved LLM or Copilot, and the client’s issue tracker. MadCap Flare or Paligo becomes worthwhile only when multi-channel reuse, localization, and governance are central requirements.
Our pick: GitHub plus VS Code and Vale for the authoring foundation, with Claude or GitHub Copilot used only against approved source material. Make executable examples, source links, and a single review channel the quality controls every client receives.