Q1: Why should I care about API documentation?
A: Good API documentation improves the DX ("developer experience") by addressing developers' needs efficiently. Here's how. 1) API documentation engages developers, helps them do real work quickly, generates trust, and boosts sales. 2) Accurate, accessible API documentation with validated code samples reduces Tech Support's call volume and Field Engineering's backlog, letting your company scale smoothly. 3) Technical writers install and use your products, read the source code (when you provide access), keystroke test the code samples, provide usability testing, and serve as QA and UX testers so your customers don't have to. 4) Developers focus on creating and shipping new features instead of patching code and doing damage control.
The result? Your developers stay (and stay happy), your customers gain confidence, and the marketplace notices.
Q2: Which tools do you use to create API documentation?
A: Our technical writers are tools-agnostic. We'll use any tool you prefer to create your content. For a list of the tools we've used, see our tools page. For example, if you're using a REST API framework such as Swagger (also known as OAI, or Open API Initiative), we'll author your documentation in Swagger. If you're creating non-REST API reference content that's embedded in your source code, we can author in Markdown or any of its variants so you can run Doxygen or Javadoc and output HTML or PDF. If you ask our recommendation for your toolchain, context, and preferred output format, we'd be happy to advise.
Ours is a customized service with real, human technical writers creating reference, tutorial, and/or operations documentation for your product's audience. The needs of that audience, and your needs for output format and maintainability, directly affect the technical writer's priorities. The tool used to author unembedded content (like a developer's quick-start tutorial or installation instructions) might differ from the one used for your API reference. Regardless, the choice of authoring tool should support creating accurate, relevant, useful content that delights your users. Picking an authoring tool too early in the content-development process causes unnecessary friction.
Q3: Why should I invest in human-written content when Swagger creates my API reference doc automatically?
A: If you design your RESTful API using Swagger, API Blueprint, or another popular API framework, you might be able to generate usable API reference documentation with one click. But when your code changes outside of the API framework, you'll need to update the doc. Most engineers hate to write and thus avoid updating the doc. This means that doc generated from API frameworks is dangerously incomplete and inaccurate after a few code revisions. Outputting REST API ref doc is easy, and it's accurate at first, but when you don't maintain, augment, and test that doc, what you get when you generate it will likely hurt you much more than it helps.
Importantly, API frameworks like Swagger only work with RESTful APIs. If you're creating any other kind of API -- including a library- or class-based API, another kind of web service API (such as SOAP, WSDL, XML-RPC, or JSON-RPC), an object-remoting API, or a hardware API -- Swagger and the other API frameworks won't help you. The only way to document those APIs is manually using human technical writers.
Finally, there's more to good API documentation than an API reference. If your API is public, you'll likely need a quick-start tutorial that helps developers get productive with a few key features in a few minutes. No API framework can 'write' that kind of deliverable; it takes an experienced technical writer who understands the audience and your technology. Good quick-start tutorials give your API credibility and lead to widespread adoption. And if your API is internal and actively used by your team, you'll need comprehensive, well-maintained reference documentation to speed onboarding; new team members can become productive quickly if they don't have to rely on disorganized, incomplete, or obsolete information. Accurate, complete, accessible doc is essential when senior developers leave the team.
Q4: How can you help my API succeed?
A: We are engineers experienced at writing documentation, and English is our native language. We'll help your API succeed by: 1) writing developer reference, quick-start, and tutorial content for your API, 2) keystroke testing code samples and configuration procedures, 3) advising on design and UI improvements, and 4) ensuring your prose consistently meets North American Business English standards and is easier to translate.
If you're not creating a RESTful API using an API framework (like Swagger or API Blueprint), you'll need a technically sophisticated tech writer to create your API documentation. Leaving API documentation to engineers results in incomplete, inconsistent, and often unusable content that alienates potential users and drives away business opportunities.
Finally, in the EU, almost all engineers who write documentation speak English only as a second language. We are engineers who write API doc and speak English as our native tongue. To get your API adopted internationally, you need your API doc written in North American Business English. And if you plan to translate, we can save you money by writing your API doc in 'Simplified English'.
5) Our engineers write our doc. Why should I hire you?
Most of our clients' software engineers start out writing their own documentation. But most engineers don't write well, and almost all would prefer instead to write code, design new features, and ship software. Engineers who aren't happy tend to leave, taking a huge amount of information about your product with them.
If your customers want better doc, or your engineers want to stop writing it themselves, invest in an independent service with decades of experience developing quality API documentation. Unlike other tech writing services in the EU, your API doc will be written by engineers who 1) understand what your audience knows (and needs to know), 2) can use your tools, 3) will test and improve not just the doc but the whole product, and 4) will do things right the first time.
If you have ever hired a technical writer who did not have engineering experience, you know that they can be very inefficient. Most non-engineers are not able to write for developers. They focus instead on explaining your product to themselves and making the output look pretty. You waste effort, time, and money while the writer does their best to interpret your product for an audience they do not -- and cannot -- understand.
Instead of hiring poets to write your API doc, hire 'documentation engineers' who won't slow your team down.
Q6: Do you need access to our source code?
A: If you grant us 'read only' access to your source code, we can read it to learn more quickly what your product does so we'll have fewer, more specific questions for your subject-matter experts (SMEs). If you grant us 'write' access to your source, we can embed API reference content in comment fields, which makes it easier to keep code and content synchronized.
If you can't grant us access to your source (for example because you're in a regulated industry such as FinTech), that's entirely fine. We'll simply have a few more questions for your engineers before we can produce the content you need. Most of our information-gathering sessions last no more than 15 minutes.
Q7): Do you have a presence in Europe?
We are based in the United States and are committed to supporting our EU customers by visiting the EU every calendar quarter. You can set up a meeting with us using https://jamesneimanconsulting.youcanbook.me or calling 001-510-205-4660.
When we visit in person or by phone, we'll ask about your documentation challenges and schedule, and discuss solutions, including pricing. We'll then send you a formal proposal, citing milestone deliverables, dates, and prices. As soon as you agree to engage, we'll emulate your development environment and get started creating the API content you need to meet your deadlines.
Q8: What if I already have API doc and just want it updated or polished?
A: We can review your existing content and propose updates, enhancements, and new content. If you want your current documentation edited or its appearance improved, we can supply the right resource who'll deliver clear, complete, attractive documentation that will impress even the most discerning audience.
Q9: What will it cost?
A: We can work on a fixed-bid or open-ended, hourly basis. If you define your requirements tightly, we would be pleased to provide a simple "not to exceed" bid for delivering specific content on your schedule. If you're more comfortable with a flexible arrangement, we can work as much or as little as you prefer until the work is done to your satisfaction.
If you want to hire a technical writer as your staff employee (rather than on contract through us), Synergistech can provide that resource for a one-time fee of 20% of the employee's annual salary. For details, contact Andrew Davis at 001-650-271-0148, synergistech.com, linkedin.com/in/synergistech, or https://www.techcommtalent.youcanbook.me.
Q10: Will you do the work here in the EU?
A: We will do the work outside of the EU, saving you up to 30 percent compared to EU-based resources. Aside from being able to deliver premium quality services more inexpensively, we engage experienced, technically sophisticated technical writers from Silicon Valley and other US technology hubs who work on a remote basis, led by Dr. James Neiman (https://www.linkedin.com/in/jamesneiman) .
Q11: Can you scale?
A: Yes. We can assemble as many engineer-caliber technical writers as you need. If you have a single small API for which you need a quick-start tutorial, you're unlikely to need more than one person's part-time effort. If you need complete reference documentation for a huge, never-documented code base on a tight schedule, we'd offer the full-time efforts of multiple technical writers, with a single point of contact (typically Dr. James Neiman).
Our experienced engineer-caliber technical writers work efficiently and accurately. They're fast, too -- you won't have to wait more than a few days for results.
We welcome the chance to discuss your documentation challenges. Just know that we probably won't tell you 'no'.
Q12: Convince me you're effective.
A: If your measure of effectiveness is happy customers, we can prove you should hire us.
As of December 2016, Dr. Neiman and his team perform technical writing services for Google, VMware, Juniper, Ooyala, and several software development startups in Silicon Valley, including Conviva, Vidyo, and Mocana. Past clients include Adobe, Cisco, PayPal, Visa, Hewlett Packard, Sony, and startups including Tokbox, Mesosphere, Magnet Software, Intel, and DJI. Most of these companies retain his services far beyond the initially contracted schedule, and many bring him back for new projects.
Detailed testimonials and writing samples are available on request.
© 2018. All Rights Reserved
James Neiman Consulting, Inc.