Comment by creshal | Hacker News Reader

Comment by creshal | Hacker News Reader

Parent Full thread

> I always had to move back an forth between different editors

Yeah, that sucks, it's much easier when you can do everything in VSCode/emacs/vim and don't have to leave your dev environment to write about what you're developing…

> WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter)

…wait, what?

> Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process)

But if I'm a lone dev, I have a personal kanban already to cover other things that aren't technical writing, and if I'm in a content team I have a full-blown kanban tool that handles multi-platform publishing. That often includes non-text content, so I wouldn't want to trade that tool for vrite either.

> The actual headless CMS (content delivery via API, integrations, etc.)

If there is to be any point to this, it better have really good integrations into existing documentation solutions.

Yet vrite's own technical documentation ist just outsourced to swagger's online service?

And it's not even good documentation: No description of possible errors, very little to no end point description, no description of what parameters do (or sometimes even are), … I don't think this is a good example for what the future of documentation should be.

Some content tools have to be for the many and not the few.

Technical writing for example is very regularly done by non technical people who are very astute with processes, steps, input and output parameters. Kind of like a power user who can also simplify and explain.

Writing things only for a personal kanban or notebook makes it harder to invite, request or actively have some collaboration. I’m increasingly using the kanban in gitlab for this reason - there are decent enough mobile apps, and it’s ready and actionable.

> Technical writing for example is very regularly done by non technical people who are very astute with processes, steps, input and output parameters. Kind of like a power user who can also simplify and explain.

While true, the tides are turning a bit here, at least for software technical writers. It's not uncommon to have a docs-as-code documentation toolchain where you're hosting all your docs in GitHub and serving them via static site. And most of the technical writers using these toolchains have no formal background in CS or previous programming know-how—myself included.

Back in the day I earned an English degree and now I'm managing PRs, generating OpenAPI files, and building out CSS/React to customize our docs site :P

Yeah, the documentation aspect is something that I started thinking about recently. That's why, currently, Vrite is more optimized for programming/developer marketing blogs rather than documentations. I'm working on proper API docs (Swagger is pretty much a better-than-nothing placeholder), these wouldn't be served by Vrite.

In basically all technical marketing teams I've worked in, things weren't as automated as you might think. Kanban was only there to manage content production stages, while the actual content was to be written in the Dropbox Paper, Notion, GDocs, etc. just to be able to collaborate and go through the review process. In the end the content had to be copy-pasted to WordPress, Ghost, etc. in an entirely manual process with many formatting issues happening in the process.

In environment you're describing Vrite would indeed be a much "harder sell". Making users move to new tool is difficult in general. That said, with proper integrations and import tools, Vrite could be an "incrementally-adoptable" CMS, that you can transition to at your own pace.

> I'm working on proper API docs (…), these wouldn't be served by Vrite.

I struggle to see what makes this a "technical content" CMS then, rather than just a generic marketing CMS.

For a generic marketing CMS aimed at marketers, the feature set makes a bit more sense. But for actual technical staff, all of these design decisions just break whatever flow the users might've had and add very little.

Personally, I see technical, programming content in 3 main categories:

- Blogging/Developer marketing content - basically all the technical blogs you see & read; Devs run personal ones for portfolio and learning, while companies to attract potential employees or sell their product (if developers are the target audience). It's the space I've worked in the most and to which Vrite was (and still is) initially addressed to.

- General documentation - all the internal/external documentation that contains usage guides, covers important concepts, etc. Basically mostly text with elements of code. I think this is the most popular use-case of the three. Vrite could handle these but it would require support for custom content (docs often embed demos, display custom notes, etc.) and integration with Git (where most of this documentation often lives).

- Code & API documentation - what I think many in this thread had in mind in regards to technical content. This is mostly code, little text and usually highly automated (not just with publishing integrations, but in direct connection with the documented codebase). This is definitely something Vrite isn't designed to do and likely couldn't do no matter the features or customizations added. There are other tools for that.

Looking back, labeling Vrite as a "CMS for technical/developer marketing" might have made it more clear what the product's goals are.

Still, I got a lot of valuable feedback from this thread that I likely wouldn't get with a perfect headline, which I'm greatful for. I'm looking to put it towards improving the "CMS for technical/developer marketing" part and creating a versitile-enough tool for handling "General documentation".

> If there is to be any point to this, it better have really good integrations into existing documentation solutions.

I'm still trying to understand this product, but it looks like this might be it's best 'feature'. For example writing all your technical Blog posts in `vrite` instance, maybe have a backlog of them managed through the kanban board, and then be able to publish them directly to Medium for example, or codecademy etc.

Not particularly useful to me, but I will play around with local deploy and see if im missing something else.

That's basically the idea. Currently most useful when you're running a technical/developer marketing blog.

Reply on news.ycombinator.com