Comment by 0xbadcafebee | Hacker News Reader

Comment by 0xbadcafebee | Hacker News Reader

Yet another company-specific reinvention of a wheel from somebody with too much money and time on their hands, and will be abandoned after a few years.

Documentation is information intended for humans to understand complex topics. Code is information intended for machines to understand complex topics. Code makes shitty documentation. Code is time-consuming, error-prone, nit-picky, and extremely verbose compared to the kinds of tools designed for humans: WISYWIG editors, buttons, windows, graphics, diagrams, audio, video.

Developers today have grown up in a world where doing anything requires writing code. They literally do not understand how to solve problems without writing code. And have even fooled themselves into thinking that writing code is a superior way for humans to solve a problem than clicking a button. So rather than have robust tools that solve our problems, we now only make tools that require us to create our own customized tools to solve our problems. Forever making slapped-together jigs for every project, rather than just buying and using a premade tool.

Confluence is what a documentation-creating solution should be. Not only does it have a WYSIWYG editor, it has custom plugins, rich content, and dynamic components, all of which can be added anywhere, immediately, with a live preview, with no training, no code, no syntax. Simply an interface for an average human to make a beautiful, useful document, quickly and easily.

From their page: "I like Markdoc because it lets us still do anything we want with code in the docs without bogging down the content authoring experience. If we need some new component, designers and engineers can whip that up. So as a writer, I can work in the docs content and stay focused."

You can do the same thing with Confluence. They just had Not-Invented-Here syndrome, and wanted to do something with their excess engineers.

You are aware that Confluence is a company specific, and proprietary, reinvention of a wheel (wikis)? And it's not even a particularly good one. It's mainly popular because it gets bundled with Jira by Atlassian. People use it because it is there; not because it is particularly good at what it does.

Your central thesis is that code and documentation are two very different things. Donald Knuth, who knows a thing or two about writing both documentation and code, invented literate programming because he disagrees with that. The key point of literate programming is that writing good code is a form of documenting your thought process for the benefit of other programmers who may have to maintain and understand your code.

Confluence is part of the reason I run an Atlassian free company. I've never been impressed with Atlassian tooling. Most of the tools I use instead support things like Markdown and some other sane things. It's fine as a poor man's word processor but it's a bit of a straight jacket. Don't get me started on Jira.

> You are aware that Confluence is a company specific, and proprietary, reinvention of a wheel (wikis)?

Am I aware that Confluence is a product created by a company for a profit in order to provide an advanced implementation of a design for specific use cases? Yes.

> And it's not even a particularly good one.

I have used 20 different wikis. None of them provide all Confluence's features or are nearly as user-friendly. Very few of them provide a robust API. Very few of them have as seamless a WYSIWYG, not to mention native Markdown support. Very few of them have advanced management capabilities. None of them have as many advanced dynamic content features, very few of them have marketplaces. It is hands-down the best tool for what it is designed for.

> Donald Knuth, who knows a thing or two about writing both documentation and code, invented literate programming because he disagrees with that.

Literate programming is ridiculous. The idea is to use a human language to tell a story and have that story be converted into computer code, with the idea that the human will understand the story better and somehow this will result in them being able to write better code. But that's stupid for two reasons: 1) writing a story is hard. communication is hard. most people just suck at it. the idea that a human will be automatically good at telling a story is in itself ridiculous. 2) humans just suck at writing code, no matter how well they understand its purpose. Traditional architecture is intended to formalize the purpose and function of the program and can result in perfectly adequate code, assuming the human actually learns how to do their job properly, which I admit is a pretty big ask for most people in tech today.

If you don't like Confluence and Jira it's probably because you haven't learned how to use them (or you just don't like that they're not free). They are incredibly flexible and extensible and the marketplace is full of tools to expand their functionality, even though the base functionality is already very powerful.

Maybe all those people who use plain text tooling for writing content, do it because... they prefer it over wysiwyg?

Confluence UX is horrible. There are a number of reasons for that, but just one is enough for me to reject it: you can't create or edit content in your own, personally optimized, automatable, text editing IDE. (And if you actually can, guess what? That's another argument against the usability of confluence, because I was either unable to find or unable to configure such a feature)

Obviously it's important for an average user to be able to edit content. But there are options that don't lock out the programmers who legitimately prefer plaintext editing.

I don’t disagree but Stripe’s case makes sense.

They are making documentation for developers.

And in fact, having good documentation and developer tooling is a core part of their value proposition.

Making it easy to look at documentation and immediately implement something that works is a core part of the Stripe UX.

So documentation can be considered as part of their product offering.

In that way it makes sense for them for it to be driven by code.

There's a dozen code documentation solutions out there. They could have adopted one that already handled Markdown and simply added extensions to it; instead they reinvented the wheel.

They sell an API product, of which documentation is an absolutely core, user-facing part of their product. It doesn’t make sense not to own something that differentiates your products value proposition.

Reply on news.ycombinator.com