Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

vrite.io

Post reply on HN
Print view View original

51–54 of 54 posts

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

#51

Post by arek_nawo »

creshal wrote: post #50
arek_nawo wrote: post #7

Earlier quoted context omitted.

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…

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

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

#52

Post by arek_nawo »

starkparker wrote: post #40
arek_nawo wrote: post #26

Earlier quoted context omitted.

- 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 conte…

> 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 u…

- For i18n I already have some idea on how this could work, as it was a reported issue: https://github.com/vriteio/vrite/issues/7

- When integrating with Git, I agree that having a single source of truth is important. In the ideal case I'd like it to work a bit like Git in VS Code. The edited content is still stored in Vrite, though it can be committed and pushed to or pulled from Git to sync. Kanban wouldn't work for that though (unless it's Vrite-only for management purposes) and some other view to represent the structure of the "documentation project" would have to be used. Also, when syncing with files in Git, some kind of format would have to be used to convert the content back and forth. Not everyone might want to use standard Markdown or MarkDoc (especially if they already have some docs in your custom format), so this should likely be customizable as well (with good defaults).

- I won't really be pushing Vrite into docs-as-code and other spaces like this. The primary use-case is dev marketing (right now) and general documentation like usage guides, explainations, etc., where the content is primarly text with addition of code (in the future). Wrote more on this in this comment: https://news.ycombinator.com/item?id=36339020

- Features like versioning, comments and edit requests are planned. Vrite already saves the history of your edits, so it's a matter of implementing a proper UI to view that.

- I agree that companies won't jump on the tool that they'll have to first develop custom extensions for. That said, the idea with extensions (and Vrite being open-source) is that, once an extension system is ready, community will be able to build and publish extensions, hopefully growing the collection as a whole. I know it's rather hard to pull of, but still possible. That's another inspiration from VS Code, btw.

- The features to fetch code snippets or handle contribution licensing make sense, though they are quite specific. In dev marketing (and often times in docs) you'll still need to write small, custom code snippets that don't necessarily exist anywhere else in the first place. On the other hand, licensing sounds like a custom need to me, and it would make most sense if it was available as an extension.

- In general, my approach to adding features is to create something as simple as possible, but highly versitile. I think highly-specific features can quickly bog-down the entire product (and its codebase). It's not always easy, but to give you a few examples for features you've discussed:

> I18N could be handled with "content variants" which would also be useful when you need to slightly adjust the content for different endpoints (though, in some cases maybe conditional inline content blocks would be better for that)

> Code snippet fetching/sync - likely a system of custom content blocks would be best for this and many other use-cases. You'll still be able to create entirely custom block that fetches content and displays it in a read-only editor or just simple view with syntax highlighting). These could be added via extensions. Adding this functionality to built-in code blocks (either directly or through hooks or something) would be too complex for the core, imo.

> Licensing - don't have anything good for this one as of yet, but likely some hooks in the mids of the editing process.

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

#53

Post by starkparker »

arek_nawo wrote: post #52
starkparker wrote: post #40

Earlier quoted context omitted.

> 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 u…

- For i18n I already have some idea on how this could work, as it was a reported issue: https://github.com/vriteio/vrite/issues/7 - When integrating with Git, I agree that having a single source of truth is important. In the ideal case I'd like it to work a bit like Git in VS Code. The edited content is still stored in Vrite, though it can be committed and pushed to or pulled from Git to sync. Kanban wouldn't work fo…

> The primary use-case is dev marketing (right now) and general documentation like usage guides, explainations, etc., where the content is primarly text with addition of code ... Looking back, labeling Vrite as a "CMS for technical/developer marketing" might have made it more clear what the product's goals are.

I think that's the way to go. There's a lot of opportunity there for a tool that's better suited to this work than blog-focused CMSs and Google Docs, but with the same sphere of pick-up-and-go accessibility ("so easy, even a product manager could use it!") without sacrificing the technical hooks to integrate that content with disparate things like LMSs, in-app help, or product docs. Runbook docs might even be a good fit depending on how well Vrite can integrate with the tools being deployed, and would be the right audience for the kinds of people who'd likely write and maintain extensions for it.

Product education teams that are allergic to the weight and complexity of LMSs would probably enjoy it too, especially if a mature extension or frontend pops up that can take one pile of content nodes and conditionally present them as blog posts, presentation slides, and paginated workbooks.

But man... the product docs space is like a 12-armed bear. I'd stay far away from even implicitly raising the possibility of Vrite being a fit for "documentation" from a product point of view. Product docs teams often have the most, and most specific, feature needs ("can you conditionalize my content based on non-Boolean feature flags while outputting to both raw and formatted HTML, PDF, and DOCX, and also linting all the content for style, reading level, and sensitivity, oh and also we need to be able to publish shared content across 36 versions of 7 product lines in 12 languages, including British localization. Also it can't fail any accessibility tests. Also can you make the logo on the output 6.5 pixels bigger, use this font I got off dafont, and match these Pantone color values from our branding"), and also the fewest technical resources to write or maintain things like extensions, and smallest budgets to pull the whole thing off — so they're also always looking at any tool that might even tangentially help them do more with less.

Post reply on HN