5 ms·

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

• 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.
  • arek_nawo 3y ago
    - 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 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 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.