The Perils of Technical Writing Gone Wrong

This year, I’ve written extensively about the need for proper technical documentation, including blog posts, white papers, and long-form articles. However, one area that tech startup owners seem to ignore is the consequences of incorrect technical documentation. In other words, what happens to your product’s (and your startup’s) reputation if your technical documentation is not only of poor quality but is also incorrect?

For instance, one of my other passions — apart from combining words to create balanced articles that add value to the brand or product I’m writing about — is data. In essence, you could say the way I combine words is data-based, but that’s a story for another day.

Imagine I am the founder of a brand-new database startup. This database is designed to store the vast amounts of data used to train large language models (LMMs). However, it is also possible to query the data directly using standard SQL. You don’t need a particular variant of SQL to query the data. In essence, this is my startup’s core value proposition.

Note: This startup is a figment of my imagination, created to illustrate this article’s central theme.

For example, the querying data that is in a table is simple:

SELECT * FROM <table_name>
WHERE <condition>;

And deleting superfluous or unnecessary data from the table is as follows:

DELETE FROM <table_name>
WHERE <condition>;

Tech Docs: Incorrect Information

However, imagine my technical writer, myself, in another universe, decides to turn these two SQL statements around in my database’s technical docs. Therefore, the docs will look similar to the following text:

To query data that is currently in a table, all you need to do is run the following SQL statement:

DELETE FROM <table_name>
WHERE <condition>;

Adding the WHERE clause is optional if you want to return all the data in the table. In this case, run the following SQL statement:

DELETE FROM <table_name>;

Can you imagine any prospective client’s reaction when they see this information? Even if they don’t know the outcome before executing these SQL statements, they will be in for a huge shock when, instead of returning a list of all the data in the table, they delete all the data in the table.

It’s safe to assume that your startup will not last very long and will not be popular with venture capitalists. Your technical documentation will make sure that most, if not all, of your prospective clients will run away — far, far away.

Tech Docs: Errors By Omission

Let’s assume now that my startup does not have any documentation. Why should I spend the time and money creating a knowledge base for my prospective clients to use? Surely, all of my prospective clients can code in SQL — after all, it is an easy language.

Yes? No?

This is where the lines become slightly blurred.

As an SQL developer, basic SQL is one of the simpler languages to use. After all, things don’t get simpler than:

SELECT * FROM <table_name>;

What about more technical, in-depth queries and SQL statements such as those found in the blog post: “Teach your LLM to Always Answer with Facts, not Fiction” by MyScale?

CREATE TABLE default.ChatArXiv (
    `abstract` String,
    `id` String,
    `vector` Array(Float32),
    `metadata` Object('JSON'),
    `pubdate` DateTime,
    `title` String,
    `categories` Array(String),
    `authors` Array(String),
    `comment` String,
    `primary_category` String,
    CONSTRAINT vec_len CHECK length(vector) = 768)
ENGINE = ReplacingMergeTree ORDER BY id SETTINGS index_granularity = 8192

INSERT INTO ChatArXiv
SELECT
  abstract, id, vector, metadata,
  parseDateTimeBestEffort(JSONExtractString(toJSONString(metadata), 'pubdate')) AS pubdate,
  JSONExtractString(toJSONString(metadata), 'title') AS title,
  arrayMap(x->trim(BOTH '"' FROM x), JSONExtractArrayRaw(toJSONString(metadata), 'categories')) AS categories,
  arrayMap(x->trim(BOTH '"' FROM x), JSONExtractArrayRaw(toJSONString(metadata), 'authors')) AS authors,
  JSONExtractString(toJSONString(metadata), 'comment') AS comment,
  JSONExtractString(toJSONString(metadata), 'primary_category') AS primary_category
FROM
  s3(
    'https://myscale-demo.s3.ap-southeast-1.amazonaws.com/chat_arxiv/data.part*.zst',
    'JSONEachRow',
    'abstract String, id String, vector Array(Float32), metadata Object(''JSON'')',
    'zstd'
  );
ALTER TABLE ChatArXiv ADD VECTOR INDEX vec_idx vector TYPE MSTG('metric_type=Cosine');

If MyScale’s founders had not spent time on their technical documents, how would prospective users know how to use their vector database?

They wouldn’t. Expert SQL developers who are well versed in working with columnar databases — MyScale is developed on top of ClickHouse — and vector databases would be able to figure out how to use MyScale. But at what expense? Would prospective clients spend the time, money, and effort learning how to use this vector database, or would they navigate to the competition, which has functional technical docs?

Note: This article is not about MyScale, except to say that its founders have spent the time, money, and effort to develop useful and functional technical documents. Rather, it is about what could potentially happen to startups and other organizations that do not craft functional documents.

Tech Docs: Too Much Information

Is it possible to add too much information to a knowledge base? I was writing a set of technical docs for another startup — a data startup that uses standard SQL to work with data in relational databases such as PostgreSQL and MySQL. Their value proposition was not that they queried the database; rather, it concerned how the data was encrypted when moving between the database and the application’s UI — user interface.

The technical documentation’s requirements were also unique in that all the standard SQL functions, such as the basic query statement with and without the where clause, had to work. Therefore, it was necessary to list all the SQL commands and explain how they worked, including examples, for each database that the startup’s product interfaced with — or was it?

I remember a data solutions engineer asking me one day if I was writing a SQL manual. I quickly responded, “Yes.” But to this day, I don’t know the answer to this question. Was I?

Conclusion: The Firecrab Take

The field of technical writing is not very well defined — which might be why it is not seen as an integral part of a tech startup’s product/service. Granted, it has improved over time. Huge organizations like Google and Ubuntu have published their ways of thinking about and doing documentation. For instance, Ubuntu has published a website called diataxis.fr. It outlines what a comprehensive set of technical docs should look like — and at Firecrab, we subscribe to this framework.

It is better to write too much than too little, but not to ramble. For instance, returning to the data encryption startup for a moment, there was a genuine possibility that I was writing too much — or an SQL manual.

But was this a bad thing? Imagine if a new developer opened this manual. Would it have made their life easier if they hadn’t had to jump to the PostgreSQL or MySQL user guide? Would having all the information they needed in one place mean their company signed up with this startup? How much money would this have been worth? Would it have offset the technical writer’s cost?