7 ms·

Show HN: I’m building open-source headless CMS for technical content

89 points by arek_nawo 3y ago

In the last few years I've been doing a lot of technical writing, both for my own programming blog and others, and I've noticed there is a lack of good tools for this kind of writing. Whether that was a programming blog post or documentation, I always had to move back an forth between different editors, and sometimes even other apps for content management and the actual content publication. A lot of copy-pasting, and wasted time. Based on this experience I decided to try and build a tool that could provide a good experience for this kind of content from writing to publishing. This (I call it Vrite) ended up being essentially a headless CMS, but optimized for technical content and a pretty unique one overall, I'd say. I tried to combine what can be seen as 3 separate products into one: - WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter) - Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process) - The actual headless CMS (content delivery via API, integrations, etc.) Most recently I decided to open-source it and see if there's any interest in such a tool. Right now the primary focus was my personal use-case (kind-of "promotional" technical writing seen in programming and start-up blogs), but I think, with more customization, something like this could extend to the documentation space and make writing and managing docs a lot easier. Let me know what do you think about this.

arek_nawo 3y ago
FYI, you have to sign in to try out Vrite (easiest through GitHub) but, for the purpose of this post, you can use the following credentials for a quick demo (at https://app.vrite.io https://app.vrite.io): Email: hello@vrite.io Password: Hello_2023 Please keep it safe and sane there :) The account will be reset every few hours. You'll likely also want to read the usage guide before jumping in: https://docs.vrite.io/getting-started https://docs.vrite.io/getting-started
deleted 3y ago
[deleted]
creshal 3y ago
> 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.
- bilekas 3y ago
  > 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.
  - arek_nawo 3y ago
    That's basically the idea. Currently most useful when you're running a technical/developer marketing blog.
- arek_nawo 3y ago
  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.
  - creshal 3y ago
    > 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.
ushakov 3y ago
How is this better than markdown?
- arek_nawo 3y ago
  Markdown is a format. Vrite is a headless CMS with many different features. On a side-note, the editor supports Markdown shortcuts and Markdown data exports.
michaelbuckbee 3y ago
I like the approach you've taken here where it's more of the complete content production and publishing service. Two things I couldn't really sort out from your docs or the site: 1. Is there support for uploading images? How is that handled? 2. Is there support for "table" data. An example: I'd like to have my headless CMS keep a list of conferences with fields for start_date, end_date and other attributes and then reference that in my site. Thanks!
- arek_nawo 3y ago
  1. Yes - currently it's just basic upload but I'm working on better asset management and optimization. 2. I don't quite understand your use-case, but: a) You can save any custom JSON metadata to an article; b) Tables in the actual content aren't supported yet;
masukomi 3y ago
I'm .... confused. What's "headless" about it? It's got a GUI. Headless means "no GUI" or.. no visible "head". hugo, jekyll and most static blogs are "headless" CMSs. This is very explicitly setting itself apart from those by HAVING a "head".
- jasonlotito 3y ago
  From the Post: "I tried to combine what can be seen as 3 separate products into one: - WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter) - Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process) - The actual headless CMS (content delivery via API, integrations, etc.)" Read the last part.
- arek_nawo 3y ago
  Hugo, Jekyll, etc. are Static Site Generators (SSGs) Content Management Systems are likes of WordPress, Ghost, Contentful and Strapi - they help you create and manage content. From those, headless CMSs form a distinct group, which only provide a dashboard for you to manage and create content with, but no built-in frontend. Instead you have to use API and other means to create your own frontend based on the content from CMS.
  - masukomi 3y ago
    but this DOESN'T "only provide a dashboard" or api. this SPECIFICALLY provides a GUI to manage it. your definition makes sense to me, but since this has a GUI it doesn't fall into that definition.
    - arek_nawo 3y ago
      Content presentation layer is the "head" in this case. Any frontend or blog you might have. The management dashboard is a separate thing not really considered in this definition - every CMS has it. Maybe this article will explain things better: https://www.contentful.com/headless-cms/ https://www.contentful.com/headless-cms/
jasonlotito 3y ago
Tried signing up. Got the email. Clicked the link. Said it was an invalid link.
- arek_nawo 3y ago
  Sorry for that bug. Just fixed it. You can try registering again.
h1fra 3y ago
Congrats on launching, that very interesting! I recently started doing a project in this area too, it's tempting but there are a lot of push back from developers to change their habits (and markdown). Anecdotally I also tried to integrate Monaco with TipTap, you did it way better than me, well played!
- arek_nawo 3y ago
  Thanks! I think that with something that allows for incremental adoption and "raw Markdown mode", this might be possible. Vrite isn't there yet but maybe it'll get there in the future. Also, yeah - integrating Monaco wasn't easy. Took me a while to get it right.
starkparker 3y ago
Is there any support for translation? If you self-host, can you use it flat-file or does it require a database? If I have my content in Markdown files in a repo, where does Vrite fit in? Why is there no search on https://docs.vrite.io/ https://docs.vrite.io/? Or am I just missing it?
- arek_nawo 3y ago
  - No they, though you can use any language you want in the editor. - Self-hosting is currently limited but, in any case, MongoDB and Redis is necessary. - A sync integration with providers like GitHub or GitLab is in the pipeline, but currently you might be able to work something out with Webhooks and Content Transformers, depending on your use-case. - Docs are fairly fresh. Agolia recommends that you have some content ready before you integrate it for the first time and I'm looking to add some more details in there, like API docs in upcoming days. When that's done, I'll add search.
  - starkparker 3y ago
    > No they, though you can use any language you want in the editor. That's going to be an obstacle for a lot of docs, support, and to a lesser extent tech marketing use cases I've worked on as a tech writer. Docusaurus and ZenDesk get a lot of value from offering integrated i18n systems. Machine translation of technical content is still not great, and all three use cases need tools to manage and track cross-language updates. > A sync integration with providers like GitHub or GitLab is in the pipeline, but currently you might be able to work something out with Webhooks and Content Transformers, depending on your use-case. As a tech writer, my use cases today are a hard, management-set docs-as-code requirement for user-facing product docs source that lives as flat files in an open-source repo, and syncing code examples used in tech marketing blog posts to tested examples in the repo to make sure we update posts (or fix regressions) when we break user-facing content. So it sounds like I'd have to wire up two-way change sync and conflict resolution between the repo and Vrite. As someone who's run docs and support KBs, my broader use case is having a single source of truth for content, and for that single source to be as tool-agnostic as possible. - I can see the value for technical marketing writer and blogging, especially in places where devs are also doing tech marketing work. I'm not sure the Vrite-specific features carry enough value to force a switch from something like Ghost or Tina, but I'd give it a spin if I was starting something from scratch. I'll say that in that context, having an integrated code editor feels like an anti-pattern compared to embedding code from a repo that I can also hook up to tests. I explicitly don't want devs to handwrite code off the tops of their heads into what'll be a blog post or documentation; it'll fall out of date with the product because it's not integrated with it/tested/in CI. It might not even be a correct example to begin with, but as an external tool that tries to feel like an IDE but isn't actually integrated with my codebase, Vrite can't know or figure that out. The Vrite editor just feels like the wrong part of the pipeline for writing code, especially when you're already going headless. If the content of just the code blocks in a piece of Vrite content could be pulled via API, I could wrap them in enough context to build tests around them, which would make me feel a lot better. The bottom line for me is that any LOC that any dev writes should live in one place; if I have to copy an example from a Vrite content piece to a file in the repo, I've created a maintenance problem. (Is that already possible? I poked at the Swagger docs but I don't see in the output whether it outputs block content as objects.) I think I'd still prefer code to be in the repo and not Vrite, but maybe I'd need to see it in use more to better understand the value of having a decent code editor in a CMS. But for: > with more customization, something like this could extend to the documentation space and make writing and managing docs a lot easier I think the scope of that challenge is quite large, and for the most part low-level writing and managing tasks aren't where there's the most pain. There's lots of opportunity to address challenges in the product docs and support KB spaces, but there are also lots of requirements needed to get a seat at that table: i18n/a11y, versioning, formal review and approval reqs, supporting branched content/staging/feature-flagged content, allowing various non-text content models like config-file examples and JSON schema. Support KBs want to associate content to tickets and measure deflection. LMS users want curriculum design tools or integrations with the ones they already use. Being an extensible headless CMS where you can code your own integrations is a valuable feature only to companies that prioritize providing engineering resources to the tech writing team, which is a very small group. So if Vrite doesn't offer things like that at least as extensions, it might not pass a day-1 requirements review even in a greenfield. (And I know Vrite doesn't and isn't designed to address any of these today — my point is that if being a product docs tool is an ambition of the tool, things like content i18n get harder to pull off the further down the development process you go. If you're serious, consider putting things like this on your roadmap if you haven't already, or evaluate their priority if you have.) The biggest killer features IMO that Vrite could bring to the docs and support KB spaces in particular are: - Clean integration with flat-file content that lives in a repo because that's often an immovable requirement, especially in projects with any open-source docs. It's not always a matter of dev preference; as a full-time tech writer I get a lot of technical tooling and tests, as well as company-cultural visibility, by having docs as or alongside code. And I've seen that value get lost in places that've switched to a CMS. - Frictionless docs content reviews and contributions from internal users that don't require the contributor to use git. Assume that product and project managers love to have opinions about the docs but never want to use git to contribute changes to them. You're already well on the way here! The only piece I don't see yet is visible change tracking and change proposals (ie. GitHub ```suggestion or GDocs edit requests). - Low-friction docs contributions from external users that don't require the contributor to use git/GitHub or a permanent login, but still automatically captures and confirms contribution licensing requirements for legal CYA. For example, expose the editing interface to semi-anonymous users, send a CLA or equivalent confirmation to a user-submitted email address, and drop the proposed changes into the Kanban. If end users can fix typos with less overhead than a GitHub workflow, and contributing devs can add docs alongside their code contributions as seamlessly and well-connected as possible for review, you can assuage a lot of the concerns orgs would have about adopting something like Vrite when their docs are already open content.
ritzaco 3y ago
There is definitely a gap for a product like this. At Ritza (a tech writing agency) we use a hacked together set of tools to accomplish this so I definitely see the need and am probably part of the target audience. Some feedback (based on a quick skim - you've probably thought about all these more than I have but just in case anything is useful) - Why include project management? It's hard to beat a tool like Linear, Trello, Jira or whatever people are already using. - I like the idea of a built-in markdown editor, but I think it's also important to allow technical people to bring their own editor or use git directly. Do you support this? If yes, I'd call it out on the landing page. Gitbook used to do this pretty well but they pivoted to a more GUI-focus and now there are weird bugs if you try to use both their editor and git directly - I agree with other comments that images are something to get right for something like this. Let people paste from clipboard, upload a file from their machine, or link to an already hosted file. Allow the user to the optimization similar to TinyPNG automatically (maybe also CDN, or at least allow integration with CDN). Assuming you're dogfooding this for your own docs, images are loading very slowly so I assume you're not doing this atm. Good luck!
- arek_nawo 3y ago
  I've freelanced for tech writing agencies and some of my experience comes from there so in a target audience you likely are :) That said, great, constructive feedback there, so let me address some points: - I don't like jumping between different tools. I prefer a consistent, great user experience when available. That's why project/content management is a big part of Vrite. That said, I'd like it to be more customizable to different use-cases people might have so, in the future, other "views" aren't out of question, e.g. list view or folder view. - I see the point. However, building a product around external products (i.e. other code/text editors) doesn't make much sense to me. However, a "raw Markdown mode" with Monaco Editor or a sync extension for editors like VS Code is in consideration for after full GFM support is implemented. Indeed Gitbook has recently been my inspiration as I'm trying to extend Vrite to handle general tech documentation rather than just dev marketing. Git is a big part of that, and I have some ideas on how to integrate it though, given that Vrite is an API-based CMS, this will be a challenging process. - Various integrations and asset management/optimization are cetainly important. Images are already handled by Cloudflare's R2 so CDN-wise it's already good - they're just too big. That said, I'm currently working on an assets manager and optimizer for Vrite.
clairity 3y ago
you've done a great job on the overall UI/UX, but as always, for me the question is where and how the product fits in the overall marketplace. this is true even for free/open source products, as it's hard to maintain momentum on stuff no one else really notices or uses. is there a pain for managing content for technical writers? yes, probably. not many products target this niche. is the pain big enough to overcome inertia? that seems questionable, but perhaps it is big enough. i doubt large businesses would even look at a fledgling product like this, as it doesn't solve enough pain for them. it seems that there might be a market in small-to-medium-sized technical businesses that have like 1 technical writer and a few guest postings to use a platform like this. but does it make sense to target developers at all? perhaps for initial marketing, but i'd conjecture that devs mainly just want to get something out on one platform (whether their own blog, or dev.to, or whatever) and perhaps secondarily on twitter (or similar) for more reach and discussion. it seems to be an uphill battle to get them to switch over to a completely different tool that requires integration to get content flowing to all the right places (which is what a headless cms requires). in any case, the positioning as a headless CMS falls flat to me. that seems to be leading with a technical detail ("headless") rather than the pain and the solution. my off-the-cuff suggestion is something more like "Content Automation" as the descriptor. similar to "Marketing Automation" (e.g., buffer, hubspot) yours is a CMS plus and an automation platform (in the making). it helps people crank out technical content and put it in all the right places to be seen by the people you want to target.
- spondylosaurus 3y ago
  Technical writer here: most TWs I know either lean hard into docs-as-code toolchains (raises hand) or fall the other way into the territory of safe but limited hosted tools, like Zendesk or ReadMe. A headless CMS seems like it falls into the awkward middle—too fiddly for people who want something that "just works," too restricting for people who do want full control to fiddle with their docs. I have to confess that I've been forced to use a headless CMS tool (Contentful) for docs in the past and I loathed it. Marketers, on the other hand, love headless CMS tools. They're the ones who forced me to use one, since our main website and blog were also built on Contentful at the time. I think headless CMS tools offer the perfect level of configuration and modular authoring for them without the daunting hurdle of having to learn to code(ish).
wiradikusuma 3y ago
I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ https://petstore.swagger.io/ ) is meh. I'm looking for something that can generate like https://stripe.com/docs/api https://stripe.com/docs/api but open source (since the OP is talking about it). I imagine a tool(chain) that can take Swagger generated from annotations in code, and combine it with a folder containing Markdown files for "free form" documentation, and generate a Hugo/Jekyll static site that can be deployed in Cloudflare Pages in docs.mycompany.com
- spondylosaurus 3y ago
  FWIW, Stripe's API docs use a bespoke toolchain that (as I heard it estimated) cost $1mil+ to build. There's a good reason Stripe is the gold standard of API reference—they invest heavily in their documentation. Considering how few other companies are willing to toss more than a few bucks at technical writers and tools, the difference is pretty stark.
  - starkparker 3y ago
    Ryan Young, a tech writer at Stripe, gave a good talk at this year's Write The Docs on some of the philosophical choices they made in structuring their docs and responding to user feedback about where it didn't land as well: https://www.youtube.com/watch?v=0OKRNQvZbL4 https://www.youtube.com/watch?v=0OKRNQvZbL4
    - spondylosaurus 3y ago
      Ooh, thanks for the link! WTD talks are always great.
- mmcclure 3y ago
  There are a few other tools out there that are at least marginally better than the default Swagger UI such as ReDoc (https://github.com/Redocly/redoc https://github.com/Redocly/redoc). When we redid the Mux docs (https://docs.mux.com/api-reference https://docs.mux.com/api-reference) we actually just decided to build our own renderer. It really wasn't as bad as you might think, at build time we pull in the JSON version of our OAS spec and render it as a static build in our Nextjs app. Don't get me wrong, it wasn't trivial, but the benefit of having complete control over the output has been well worth it.
wkdneidbwf 3y ago
i’m not sure i understand “headless” in this context. i thought that meant cli driven, but that’s not the case
newscracker 3y ago
A few comments that I hope may help bring more clarity for your intended audience: * Your website looks slick and kinda well designed (though there seems to be too much information moving around). * The documentation starts with getting the user to sign up for the hosted version (SaaS). * There is no pricing information or FAQ about pricing and business model. * Though the code seems to be on GitHub and the license there is stated as AGPL, there are no prominent links to anything about self-hosting either on GitHub or on your main site. So I’m not sure why this is AGPL licensed but also talks the user into signing up to the hosted version in the docs. I think the self-hosting documentation will help bring more people to try it within their own environment without worrying as much about privacy and security.
- arek_nawo 3y ago
  Like I've said in the original post, the decision to open-source was made only a while back, after the core was developed as primarily a closed-source service. I decided it'd be very hard to compete with a closed-source CMS, let alone one targeted at DEV, so I decided to go with it - to build community and move the idea forward in general. Still, actually adjusting it to be easily self-hostable will take time, as I wrote here: https://docs.vrite.io/self-hosting https://docs.vrite.io/self-hosting The intention isn't to "talk users into" the hosted version, but just build interest, for which the hosted version serves best at the moment. Other points r.e. landing page are valid and I'm generally aware that I should focus more on content than design. Easier said than done though :)
punkbit 3y ago
If you don't mind some feedback, I'll share some thoughts: My professional and personal experience tells me that markdown and a static site generators are the best workflow for technical writing. I can automate quite a lot, and do proper version control. A GUI CRUD and all the related requirements such as databases, would get on the way to keep the documentation in sync with the actual codebase.
- starkparker 3y ago
  I'd agree with you on software product docs, and also note that tech writing is considerably broader than software and docs.
MilStdJunkie 3y ago
I feel like a lot of these problems have been dealt with already in the lightweight markup ecosystem, and the other problems are solved in the VSC extensions. While the "Big XML Specs" (aka DITA, S1000D, DocBook) allow you to re-use content, you can get the same functionality from Asciidoc or ReStructuredText. You can ALSO get the same functionality from Markdown, but it requires extensions, and the problem with THAT is that the functionality will change from instance to instance. Adoc and RST have transclusion and conditionals in core. I think Asciidoc is the right way to go here, but my reasoning might not be applicable for someone outside of the hard industries (manufacturing, aerospace, defense). But just because you have transclusion and conditionals, that doesn't mean you're ready to start re-using content. Content re-use, the concept often called Component Content Systems, introduces a level of complexity that's almost always underestimated, and it's inherently dependent on information architecture in a way that a unified or natural document isn't. Information architecture is going to be driven by product architecture, and if the product architecture is missing or wrong, then you probably shouldn't try to architect the documentation. Re-use only works when the product makes sense. Here's an example. Let's say my org makes planes. We make a product called SuperPlane. It has three variants, A, B, and C. Each of them is composed of modules: Wing, Fuel, Cockpit, Propulsion, Empennage. The product, in this case, is architected. SuperPlane modules share enough commonality so that the documentation for each module can be shared across all variants. So I have a "book" for A, for B, for C, and a single document module for Wing. Inside of the document module there are blocks of conditional content, for each of the variants. So when I run a book for A, it pulls in the Wing section, the it's customized for A as the conditionals are processed. Same for B and C: multiple deliverables, re-using the same modules. My information architecture - filenaming, chunking, conditions - rides from the product architecture. The product architecture is solid, and so am I. Now let's say our Maximum Leader has decided to acquire a car company, and has decided to make the flying car the D variant of SuperPlane. It's got an integrated wing and fuel module, so now, we lose content history with our A-B-C Wing and Fuel modules, in spite of the fact it's supposed to be equivalent. Its cockpit module shares no interfaces or commonality with the other cockpuit modules - so the module for Cockpit has a gigantic conditional section that largely parallels the others, in the same module, which makes assessing change impact really difficult. With the introduction of Variant D Superplane, the Superplane product is no longer architected, and our information architecture got blown up as well. This is the core reason why component content systems (CCSs) are so hard. The end product depends on lots of stuff outside of the tech writers' wheelhouse, and unlike a document - which you can look at any old time you like - when the information architecture is busted in a CCS you might not even be able to get your content out of it. CCSs replace the natural language of document structure with the constructed language of information architecture, which is a bigger leap than I think many people realize; it fundamentally changes what your documents actually are. The original concept of CCSs did not come from a linguistic or information background, they were largely psychology academics and/or dealing with an EXTREMELY limited corpus, and you can see the trace of this in the awesome pattern of failure for most CCS systems to the present day. This is markup-agnostic; it doesn't matter if you're doing it in S1000D, DITA, DocBook, ReStructuredText, or Asciidoc. So how do you check product architecture? That is complicated, and it's going to depend on your industry. In a codebase, there are a LOT of tools for assessing variance, far too detailed a topic to get into here. In hardware and manufacturing, this is the sandbox of config management, but something I've found useful is warehousing all the product data I can get my hands on, then assessing an equivalence factor for any arbitrary grouping of final assemblies. When the equivalence factor is outside of a given range, I know that I might have problems if I treat those assemblies as "variants" of some fictional "product". Once it ventures outside of an acceptable equivalence, I will often assess that "variant" as its own pseudo-product for the purpose of information architecture. This saves so, so, so very many headaches - and if they ever do decide to rebaseline everything, we can make a task to reassess and, if commonality is now found, pull stuff together (within reason, some regulatory problems with wiping out procedures willy nilly).
ravisagar 3y ago
Is anyone aware of headless API first issue tracking tool?

89 points by arek_nawo 3y ago

arek_nawo 3y ago

FYI, you have to sign in to try out Vrite (easiest through GitHub) but, for the purpose of this post, you can use the following credentials for a quick demo (at https://app.vrite.io https://app.vrite.io): Email: hello@vrite.io Password: Hello_2023 Please keep it safe and sane there :) The account will be reset every few hours. You'll likely also want to read the usage guide before jumping in: https://docs.vrite.io/getting-started https://docs.vrite.io/getting-started

deleted 3y ago

[deleted]

creshal 3y ago

> 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.

bilekas 3y ago
> 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.
- arek_nawo 3y ago
  That's basically the idea. Currently most useful when you're running a technical/developer marketing blog.
arek_nawo 3y ago
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.
- creshal 3y ago
  > 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.

ushakov 3y ago

How is this better than markdown?

arek_nawo 3y ago
Markdown is a format. Vrite is a headless CMS with many different features. On a side-note, the editor supports Markdown shortcuts and Markdown data exports.

michaelbuckbee 3y ago

I like the approach you've taken here where it's more of the complete content production and publishing service. Two things I couldn't really sort out from your docs or the site: 1. Is there support for uploading images? How is that handled? 2. Is there support for "table" data. An example: I'd like to have my headless CMS keep a list of conferences with fields for start_date, end_date and other attributes and then reference that in my site. Thanks!

arek_nawo 3y ago
1. Yes - currently it's just basic upload but I'm working on better asset management and optimization. 2. I don't quite understand your use-case, but: a) You can save any custom JSON metadata to an article; b) Tables in the actual content aren't supported yet;

masukomi 3y ago

I'm .... confused. What's "headless" about it? It's got a GUI. Headless means "no GUI" or.. no visible "head". hugo, jekyll and most static blogs are "headless" CMSs. This is very explicitly setting itself apart from those by HAVING a "head".

jasonlotito 3y ago
From the Post: "I tried to combine what can be seen as 3 separate products into one: - WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter) - Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process) - The actual headless CMS (content delivery via API, integrations, etc.)" Read the last part.
arek_nawo 3y ago
Hugo, Jekyll, etc. are Static Site Generators (SSGs) Content Management Systems are likes of WordPress, Ghost, Contentful and Strapi - they help you create and manage content. From those, headless CMSs form a distinct group, which only provide a dashboard for you to manage and create content with, but no built-in frontend. Instead you have to use API and other means to create your own frontend based on the content from CMS.
- masukomi 3y ago
  but this DOESN'T "only provide a dashboard" or api. this SPECIFICALLY provides a GUI to manage it. your definition makes sense to me, but since this has a GUI it doesn't fall into that definition.
  - arek_nawo 3y ago
    Content presentation layer is the "head" in this case. Any frontend or blog you might have. The management dashboard is a separate thing not really considered in this definition - every CMS has it. Maybe this article will explain things better: https://www.contentful.com/headless-cms/ https://www.contentful.com/headless-cms/

jasonlotito 3y ago

Tried signing up. Got the email. Clicked the link. Said it was an invalid link.

arek_nawo 3y ago
Sorry for that bug. Just fixed it. You can try registering again.

h1fra 3y ago

Congrats on launching, that very interesting! I recently started doing a project in this area too, it's tempting but there are a lot of push back from developers to change their habits (and markdown). Anecdotally I also tried to integrate Monaco with TipTap, you did it way better than me, well played!

arek_nawo 3y ago
Thanks! I think that with something that allows for incremental adoption and "raw Markdown mode", this might be possible. Vrite isn't there yet but maybe it'll get there in the future. Also, yeah - integrating Monaco wasn't easy. Took me a while to get it right.

starkparker 3y ago

Is there any support for translation? If you self-host, can you use it flat-file or does it require a database? If I have my content in Markdown files in a repo, where does Vrite fit in? Why is there no search on https://docs.vrite.io/ https://docs.vrite.io/? Or am I just missing it?

arek_nawo 3y ago
- No they, though you can use any language you want in the editor. - Self-hosting is currently limited but, in any case, MongoDB and Redis is necessary. - A sync integration with providers like GitHub or GitLab is in the pipeline, but currently you might be able to work something out with Webhooks and Content Transformers, depending on your use-case. - Docs are fairly fresh. Agolia recommends that you have some content ready before you integrate it for the first time and I'm looking to add some more details in there, like API docs in upcoming days. When that's done, I'll add search.
- starkparker 3y ago
  > No they, though you can use any language you want in the editor. That's going to be an obstacle for a lot of docs, support, and to a lesser extent tech marketing use cases I've worked on as a tech writer. Docusaurus and ZenDesk get a lot of value from offering integrated i18n systems. Machine translation of technical content is still not great, and all three use cases need tools to manage and track cross-language updates. > A sync integration with providers like GitHub or GitLab is in the pipeline, but currently you might be able to work something out with Webhooks and Content Transformers, depending on your use-case. As a tech writer, my use cases today are a hard, management-set docs-as-code requirement for user-facing product docs source that lives as flat files in an open-source repo, and syncing code examples used in tech marketing blog posts to tested examples in the repo to make sure we update posts (or fix regressions) when we break user-facing content. So it sounds like I'd have to wire up two-way change sync and conflict resolution between the repo and Vrite. As someone who's run docs and support KBs, my broader use case is having a single source of truth for content, and for that single source to be as tool-agnostic as possible. - I can see the value for technical marketing writer and blogging, especially in places where devs are also doing tech marketing work. I'm not sure the Vrite-specific features carry enough value to force a switch from something like Ghost or Tina, but I'd give it a spin if I was starting something from scratch. I'll say that in that context, having an integrated code editor feels like an anti-pattern compared to embedding code from a repo that I can also hook up to tests. I explicitly don't want devs to handwrite code off the tops of their heads into what'll be a blog post or documentation; it'll fall out of date with the product because it's not integrated with it/tested/in CI. It might not even be a correct example to begin with, but as an external tool that tries to feel like an IDE but isn't actually integrated with my codebase, Vrite can't know or figure that out. The Vrite editor just feels like the wrong part of the pipeline for writing code, especially when you're already going headless. If the content of just the code blocks in a piece of Vrite content could be pulled via API, I could wrap them in enough context to build tests around them, which would make me feel a lot better. The bottom line for me is that any LOC that any dev writes should live in one place; if I have to copy an example from a Vrite content piece to a file in the repo, I've created a maintenance problem. (Is that already possible? I poked at the Swagger docs but I don't see in the output whether it outputs block content as objects.) I think I'd still prefer code to be in the repo and not Vrite, but maybe I'd need to see it in use more to better understand the value of having a decent code editor in a CMS. But for: > with more customization, something like this could extend to the documentation space and make writing and managing docs a lot easier I think the scope of that challenge is quite large, and for the most part low-level writing and managing tasks aren't where there's the most pain. There's lots of opportunity to address challenges in the product docs and support KB spaces, but there are also lots of requirements needed to get a seat at that table: i18n/a11y, versioning, formal review and approval reqs, supporting branched content/staging/feature-flagged content, allowing various non-text content models like config-file examples and JSON schema. Support KBs want to associate content to tickets and measure deflection. LMS users want curriculum design tools or integrations with the ones they already use. Being an extensible headless CMS where you can code your own integrations is a valuable feature only to companies that prioritize providing engineering resources to the tech writing team, which is a very small group. So if Vrite doesn't offer things like that at least as extensions, it might not pass a day-1 requirements review even in a greenfield. (And I know Vrite doesn't and isn't designed to address any of these today — my point is that if being a product docs tool is an ambition of the tool, things like content i18n get harder to pull off the further down the development process you go. If you're serious, consider putting things like this on your roadmap if you haven't already, or evaluate their priority if you have.) The biggest killer features IMO that Vrite could bring to the docs and support KB spaces in particular are: - Clean integration with flat-file content that lives in a repo because that's often an immovable requirement, especially in projects with any open-source docs. It's not always a matter of dev preference; as a full-time tech writer I get a lot of technical tooling and tests, as well as company-cultural visibility, by having docs as or alongside code. And I've seen that value get lost in places that've switched to a CMS. - Frictionless docs content reviews and contributions from internal users that don't require the contributor to use git. Assume that product and project managers love to have opinions about the docs but never want to use git to contribute changes to them. You're already well on the way here! The only piece I don't see yet is visible change tracking and change proposals (ie. GitHub ```suggestion or GDocs edit requests). - Low-friction docs contributions from external users that don't require the contributor to use git/GitHub or a permanent login, but still automatically captures and confirms contribution licensing requirements for legal CYA. For example, expose the editing interface to semi-anonymous users, send a CLA or equivalent confirmation to a user-submitted email address, and drop the proposed changes into the Kanban. If end users can fix typos with less overhead than a GitHub workflow, and contributing devs can add docs alongside their code contributions as seamlessly and well-connected as possible for review, you can assuage a lot of the concerns orgs would have about adopting something like Vrite when their docs are already open content.

ritzaco 3y ago

There is definitely a gap for a product like this. At Ritza (a tech writing agency) we use a hacked together set of tools to accomplish this so I definitely see the need and am probably part of the target audience. Some feedback (based on a quick skim - you've probably thought about all these more than I have but just in case anything is useful) - Why include project management? It's hard to beat a tool like Linear, Trello, Jira or whatever people are already using. - I like the idea of a built-in markdown editor, but I think it's also important to allow technical people to bring their own editor or use git directly. Do you support this? If yes, I'd call it out on the landing page. Gitbook used to do this pretty well but they pivoted to a more GUI-focus and now there are weird bugs if you try to use both their editor and git directly - I agree with other comments that images are something to get right for something like this. Let people paste from clipboard, upload a file from their machine, or link to an already hosted file. Allow the user to the optimization similar to TinyPNG automatically (maybe also CDN, or at least allow integration with CDN). Assuming you're dogfooding this for your own docs, images are loading very slowly so I assume you're not doing this atm. Good luck!

arek_nawo 3y ago
I've freelanced for tech writing agencies and some of my experience comes from there so in a target audience you likely are :) That said, great, constructive feedback there, so let me address some points: - I don't like jumping between different tools. I prefer a consistent, great user experience when available. That's why project/content management is a big part of Vrite. That said, I'd like it to be more customizable to different use-cases people might have so, in the future, other "views" aren't out of question, e.g. list view or folder view. - I see the point. However, building a product around external products (i.e. other code/text editors) doesn't make much sense to me. However, a "raw Markdown mode" with Monaco Editor or a sync extension for editors like VS Code is in consideration for after full GFM support is implemented. Indeed Gitbook has recently been my inspiration as I'm trying to extend Vrite to handle general tech documentation rather than just dev marketing. Git is a big part of that, and I have some ideas on how to integrate it though, given that Vrite is an API-based CMS, this will be a challenging process. - Various integrations and asset management/optimization are cetainly important. Images are already handled by Cloudflare's R2 so CDN-wise it's already good - they're just too big. That said, I'm currently working on an assets manager and optimizer for Vrite.

clairity 3y ago

you've done a great job on the overall UI/UX, but as always, for me the question is where and how the product fits in the overall marketplace. this is true even for free/open source products, as it's hard to maintain momentum on stuff no one else really notices or uses. is there a pain for managing content for technical writers? yes, probably. not many products target this niche. is the pain big enough to overcome inertia? that seems questionable, but perhaps it is big enough. i doubt large businesses would even look at a fledgling product like this, as it doesn't solve enough pain for them. it seems that there might be a market in small-to-medium-sized technical businesses that have like 1 technical writer and a few guest postings to use a platform like this. but does it make sense to target developers at all? perhaps for initial marketing, but i'd conjecture that devs mainly just want to get something out on one platform (whether their own blog, or dev.to, or whatever) and perhaps secondarily on twitter (or similar) for more reach and discussion. it seems to be an uphill battle to get them to switch over to a completely different tool that requires integration to get content flowing to all the right places (which is what a headless cms requires). in any case, the positioning as a headless CMS falls flat to me. that seems to be leading with a technical detail ("headless") rather than the pain and the solution. my off-the-cuff suggestion is something more like "Content Automation" as the descriptor. similar to "Marketing Automation" (e.g., buffer, hubspot) yours is a CMS plus and an automation platform (in the making). it helps people crank out technical content and put it in all the right places to be seen by the people you want to target.

spondylosaurus 3y ago
Technical writer here: most TWs I know either lean hard into docs-as-code toolchains (raises hand) or fall the other way into the territory of safe but limited hosted tools, like Zendesk or ReadMe. A headless CMS seems like it falls into the awkward middle—too fiddly for people who want something that "just works," too restricting for people who do want full control to fiddle with their docs. I have to confess that I've been forced to use a headless CMS tool (Contentful) for docs in the past and I loathed it. Marketers, on the other hand, love headless CMS tools. They're the ones who forced me to use one, since our main website and blog were also built on Contentful at the time. I think headless CMS tools offer the perfect level of configuration and modular authoring for them without the daunting hurdle of having to learn to code(ish).

wiradikusuma 3y ago

I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ https://petstore.swagger.io/ ) is meh. I'm looking for something that can generate like https://stripe.com/docs/api https://stripe.com/docs/api but open source (since the OP is talking about it). I imagine a tool(chain) that can take Swagger generated from annotations in code, and combine it with a folder containing Markdown files for "free form" documentation, and generate a Hugo/Jekyll static site that can be deployed in Cloudflare Pages in docs.mycompany.com

spondylosaurus 3y ago
FWIW, Stripe's API docs use a bespoke toolchain that (as I heard it estimated) cost $1mil+ to build. There's a good reason Stripe is the gold standard of API reference—they invest heavily in their documentation. Considering how few other companies are willing to toss more than a few bucks at technical writers and tools, the difference is pretty stark.
- starkparker 3y ago
  Ryan Young, a tech writer at Stripe, gave a good talk at this year's Write The Docs on some of the philosophical choices they made in structuring their docs and responding to user feedback about where it didn't land as well: https://www.youtube.com/watch?v=0OKRNQvZbL4 https://www.youtube.com/watch?v=0OKRNQvZbL4
  - spondylosaurus 3y ago
    Ooh, thanks for the link! WTD talks are always great.
mmcclure 3y ago
There are a few other tools out there that are at least marginally better than the default Swagger UI such as ReDoc (https://github.com/Redocly/redoc https://github.com/Redocly/redoc). When we redid the Mux docs (https://docs.mux.com/api-reference https://docs.mux.com/api-reference) we actually just decided to build our own renderer. It really wasn't as bad as you might think, at build time we pull in the JSON version of our OAS spec and render it as a static build in our Nextjs app. Don't get me wrong, it wasn't trivial, but the benefit of having complete control over the output has been well worth it.

wkdneidbwf 3y ago

i’m not sure i understand “headless” in this context. i thought that meant cli driven, but that’s not the case

newscracker 3y ago

A few comments that I hope may help bring more clarity for your intended audience: * Your website looks slick and kinda well designed (though there seems to be too much information moving around). * The documentation starts with getting the user to sign up for the hosted version (SaaS). * There is no pricing information or FAQ about pricing and business model. * Though the code seems to be on GitHub and the license there is stated as AGPL, there are no prominent links to anything about self-hosting either on GitHub or on your main site. So I’m not sure why this is AGPL licensed but also talks the user into signing up to the hosted version in the docs. I think the self-hosting documentation will help bring more people to try it within their own environment without worrying as much about privacy and security.

arek_nawo 3y ago
Like I've said in the original post, the decision to open-source was made only a while back, after the core was developed as primarily a closed-source service. I decided it'd be very hard to compete with a closed-source CMS, let alone one targeted at DEV, so I decided to go with it - to build community and move the idea forward in general. Still, actually adjusting it to be easily self-hostable will take time, as I wrote here: https://docs.vrite.io/self-hosting https://docs.vrite.io/self-hosting The intention isn't to "talk users into" the hosted version, but just build interest, for which the hosted version serves best at the moment. Other points r.e. landing page are valid and I'm generally aware that I should focus more on content than design. Easier said than done though :)

punkbit 3y ago

If you don't mind some feedback, I'll share some thoughts: My professional and personal experience tells me that markdown and a static site generators are the best workflow for technical writing. I can automate quite a lot, and do proper version control. A GUI CRUD and all the related requirements such as databases, would get on the way to keep the documentation in sync with the actual codebase.

starkparker 3y ago
I'd agree with you on software product docs, and also note that tech writing is considerably broader than software and docs.

MilStdJunkie 3y ago

I feel like a lot of these problems have been dealt with already in the lightweight markup ecosystem, and the other problems are solved in the VSC extensions. While the "Big XML Specs" (aka DITA, S1000D, DocBook) allow you to re-use content, you can get the same functionality from Asciidoc or ReStructuredText. You can ALSO get the same functionality from Markdown, but it requires extensions, and the problem with THAT is that the functionality will change from instance to instance. Adoc and RST have transclusion and conditionals in core. I think Asciidoc is the right way to go here, but my reasoning might not be applicable for someone outside of the hard industries (manufacturing, aerospace, defense). But just because you have transclusion and conditionals, that doesn't mean you're ready to start re-using content. Content re-use, the concept often called Component Content Systems, introduces a level of complexity that's almost always underestimated, and it's inherently dependent on information architecture in a way that a unified or natural document isn't. Information architecture is going to be driven by product architecture, and if the product architecture is missing or wrong, then you probably shouldn't try to architect the documentation. Re-use only works when the product makes sense. Here's an example. Let's say my org makes planes. We make a product called SuperPlane. It has three variants, A, B, and C. Each of them is composed of modules: Wing, Fuel, Cockpit, Propulsion, Empennage. The product, in this case, is architected. SuperPlane modules share enough commonality so that the documentation for each module can be shared across all variants. So I have a "book" for A, for B, for C, and a single document module for Wing. Inside of the document module there are blocks of conditional content, for each of the variants. So when I run a book for A, it pulls in the Wing section, the it's customized for A as the conditionals are processed. Same for B and C: multiple deliverables, re-using the same modules. My information architecture - filenaming, chunking, conditions - rides from the product architecture. The product architecture is solid, and so am I. Now let's say our Maximum Leader has decided to acquire a car company, and has decided to make the flying car the D variant of SuperPlane. It's got an integrated wing and fuel module, so now, we lose content history with our A-B-C Wing and Fuel modules, in spite of the fact it's supposed to be equivalent. Its cockpit module shares no interfaces or commonality with the other cockpuit modules - so the module for Cockpit has a gigantic conditional section that largely parallels the others, in the same module, which makes assessing change impact really difficult. With the introduction of Variant D Superplane, the Superplane product is no longer architected, and our information architecture got blown up as well. This is the core reason why component content systems (CCSs) are so hard. The end product depends on lots of stuff outside of the tech writers' wheelhouse, and unlike a document - which you can look at any old time you like - when the information architecture is busted in a CCS you might not even be able to get your content out of it. CCSs replace the natural language of document structure with the constructed language of information architecture, which is a bigger leap than I think many people realize; it fundamentally changes what your documents actually are. The original concept of CCSs did not come from a linguistic or information background, they were largely psychology academics and/or dealing with an EXTREMELY limited corpus, and you can see the trace of this in the awesome pattern of failure for most CCS systems to the present day. This is markup-agnostic; it doesn't matter if you're doing it in S1000D, DITA, DocBook, ReStructuredText, or Asciidoc. So how do you check product architecture? That is complicated, and it's going to depend on your industry. In a codebase, there are a LOT of tools for assessing variance, far too detailed a topic to get into here. In hardware and manufacturing, this is the sandbox of config management, but something I've found useful is warehousing all the product data I can get my hands on, then assessing an equivalence factor for any arbitrary grouping of final assemblies. When the equivalence factor is outside of a given range, I know that I might have problems if I treat those assemblies as "variants" of some fictional "product". Once it ventures outside of an acceptable equivalence, I will often assess that "variant" as its own pseudo-product for the purpose of information architecture. This saves so, so, so very many headaches - and if they ever do decide to rebaseline everything, we can make a task to reassess and, if commonality is now found, pull stuff together (within reason, some regulatory problems with wiping out procedures willy nilly).

ravisagar 3y ago

Is anyone aware of headless API first issue tracking tool?