7 ms·

Writerside – a new technical writing environment from JetBrains

265 points by thatxliner 3y ago

AceyMan 3y ago
Looking at the landing page it appears they are aligning the product with the Diataxis framework (web: Diataxis.fr). I see that as a good thing.
- kaycebasques 3y ago
  I don't see much to support that claim. Tutorials and references are very common concepts among technical writers, with a history that long predates Diataxis...
  - spondylosaurus 3y ago
    Is DITA older than Diataxis? Even if it is, DITA's still far from the first, but you know how they love their topic-based authoring in DITAland....
    - pjmlp 3y ago
      I was using DITA back in 2007 for technical documentation, apparently Diataxis seems quite recent, assuming I have found the right date.
deleted 3y ago
[deleted]
menacingly 3y ago
Generally a big fan of jetbrains, but can't shake that the name sounds like the crime of murdering a writer
- rob74 3y ago
  Interesting association - but wouldn't that be Writer-cide?
  - xwowsersx 3y ago
    Yeah. "sounds like", not "reads like"
- gjvc 3y ago
  [flagged]
yodon 3y ago
I use SpecFlow (Gherkin for the .NET world), and what I really want is to be able to tie my tutorials to my test cases so I get a CI/CD error if I make a code change that breaks a tutorial or change a tutorial to have instructions that don't actually work.
jw_cook 3y ago
Interesting, that's not what I expected. So it seems like it's an opinionated integration between an editor and a Markdown-based static site generator with its own set of XML-based markup features. Sounds like that has potential. Its docs are quite nice (as I would hope to see from a documentation tool) and a good demo of what it's capable of, but after spending a bit of time looking them over I still have several questions: * How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? * Most people who write a lot of docs are already invested in some documentation toolset or another. What does this tool offer that would make it worthwhile to switch? * From the overview page: "This project developed out of hundreds of customer interviews and 10+ years of working on the IntelliJ Platform documentation. These experiences gave us a long list of features to build and problems to solve." I'd be interested to hear more about specific lessons learned from these interviews and how Writerside addresses them.
- spondylosaurus 3y ago
  > How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? Looks like this has a GUI, for one, which is potentially a big selling point for the not-so-technical crowd. I know there are headless CMS tools out there that you can hook up to almost any SSG, but even getting that set up is way too big of a stumbling block for the kind of tech writer who doesn't want to tinker or use the CLI or any of that. At that point you'd probably just opt to use Zendesk or whatever (boo). > What does this tool offer that would make it worthwhile to switch? Even with the GUI stuff, I'm also wondering whether there's anything here enticing enough to switch. If your docs are already entrenched in some other ancient tool, it can be hard to get the resources/support to switch even if you want to switch, which many writers may not. OTOH anyone who wants to do docs-as-code probably already is, and the kinds of environments where docs-as-code thrives are the kinds of environments where it's not unreasonable to ask your writers to learn Git.
- troupo 3y ago
  > How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? Those are SSGs, not documentation systems. Just because they are used in that way doesn't make them such. > I'd be interested to hear more about specific lessons learned from these interviews and how Writerside addresses them. Some of them are listed on the project's front page
deleted 3y ago
[deleted]
kaycebasques 3y ago
I wonder if JetBrains is going for the professional technical writer (TW) market outside of software development. Think aviation, military, manufacturing, etc. They seem to use paid writing suites quite a lot. MadCap Flare is a name you hear often. TW teams writing in B2C contexts often use these suites too. JetBrains markets it as docs-as-code though, a concept that software-development-focused technical writers would care most about. There is also the angle that a lot of engineers don't want to deal with any bullshit setting up a docs authoring env. If this tool makes it easier for them to contribute docs, I could see that as a way to get solid adoption. The docs quality automation sounds interesting. Couldn't find a link that explains more. (I'm on mobile.) (I've been a TW for ~10 years.)
- pbowyer 3y ago
  > They seem to use paid writing suites quite a lot. MadCap Flare is a name you hear often. TW teams writing in B2C contexts often use these suites too. I didn't know these suites existed. What other ones are popular, and what's their selling point?
  - spondylosaurus 3y ago
    MadCap is the big one I hear about, then maybe FrameMaker at a distant second and plain old Microsoft Word. As a software technical writer who loves docs-as-code I don't know how the writers in manufacturing and aviation and whatnot put up with those tools...
    - mjoneill 3y ago
      MadCap Flare was an awesome product. It grew out of the old BlueSky "RoboHelp" suite (which was also awesome) and could be used to output to many different formats (online help, web help, print docs, confluence). It's been a while, but I think you could even use FrameMaker to author and still use Flare to transform output to all its supported formats. It's been a long time since I immersed myself in this world, so apologies if my memory is less than perfect.
    - mjoneill 3y ago
mikro2nd 3y ago
No Asciidoc? I know (and use daily) the IntelliJ Asciidoc plugin, so it's surprising to me that they make a writing plugin/environment and don't support AD out of the box. eta: Having now had a closer look, some more thoughts: The tool is clearly focussed on writing docs "for a website"; for external consumption. (For whatever value you choose for "external".) Definitely not for internal-to-a-project docs that you'd want side-by-side in a code project[1]. So no wikilinking between pages, which is (for me) a deal-breaker, making this thing basically just a previewing Markdown editor that also does XML source. Well, it's early days, so let's hope that the tool becomes all it might be someday. But if you're doing "for external consumption via a website" docs, then maybe this can be useful to you, though it's hard to see what it's doing that a dozen other previewing Markdown editors don't already do, and some better. [1] Yes, I'm aware that there are several plugins to IJ that do side-by-side note-making in projects. I've tried (probably) all of them, and they're all badly deficient in one way or another.
- janosdebugs 3y ago
  This. Any time I saw a more complex doc work with several editors and reviewers, it was in Asciidoc.
- byb 3y ago
  I want to second your comment. AsciiDoc is growing in popularity. A year ago I surveyed a dozen tools and went all in with it. I'd like to see IJ take it a step further beyond AsciiDoc, by supporting Antora to generate and deploy static websites. When combined with Antora-Assembler its also possible to generate PDFs using the ruby-based AsciiDoctor PDF. I'm currently introducing a Docs-as-Code workflow using Visual Studio Code at my organization, because of the very permissive license terms of VSC and the decent AsciiDoc preview function. Mostly though, I find reading adoc files quite easy until lots of Antora snippets (which don't resolve) and conditions start getting added in. A lot of technical writers I've met have had a hard time understanding XML, which is nothing to say of the average office worker who wants to open up their old copy of Office 97 and write a completely unstructed document with a WYSIWIG interface. IJ IDE licenses start to add up, so if IJ is competitive against Oxygen, this might make sense for a lot of organizations to jump over.
eskaytwo 3y ago
If this could generate Confluence that would overlap well for a lot of JetBrains IDE users
- martypitt 3y ago
  Jetbrains have a pretty decent Knowledge base inside YouTrack (their issue tracker tool)
- steamer25 3y ago
  Was actually thinking, once you've integrated it with a CI action and cheap static web host, this replaces Confluence in many ways. Looks like the basic editor is and will remain free. This could be a pretty great approach. What should be especially nice is being able to blend automatically-generated documentation and e.g., automated testing reports, etc. in the same host/site as more manually curated documentation. Maybe this would also solve the other problem with Confluence--that people end up using it as a junk drawer. DO NOT PILE YOUR TRANSIENT MEETING NOTES IN THE SAME SPACE AS YOUR TECHNICAL DOCUMENTATION PEOPLE. It fills the search index with noise and makes it impossible to find any information except the stuff that was only relevant for the two days after it was written three years ago. On that note, it seems like the primary downside of this is that you don't get search indexing at all unless you also configure and integrate something like OpenSearch.
ez_mmk 3y ago
If it exists there is a jetbrains tool for it
rob74 3y ago
Markdown and XML are nice, but what about more advanced documentation formats like OpenAPI? For one recent project, I set up automatic generation of the OpenAPI docs from (much more compact and flexible) CUE definitions (https://cuelang.org/ https://cuelang.org/) - which has the bonus of also being able to test the API against the definitions. JetBrains has a CUE plugin, but it's really barebones (doesn't even support jumping from the usage of a schema to its definition). Of course the possibilities when generating docs are endless - just think of the various syntaxes for doc comments, embedding examples/tests in source code etc., and each language tends to have its own standard (either built in or third party).
- lananovikova 3y ago
  openAPI docs support is mentioned https://www.jetbrains.com/help/writerside/api-documentation.html https://www.jetbrains.com/help/writerside/api-documentation....
gadders 3y ago
Interesting tool, but from the first video on the page it looks like you have to write in markdown and then look at the wysiwyg window to see what your output would be like. That seems backwards to me, if the target is writers. A better tool would let you create in a wysiwyg MS Word-like editor, but save all docs as markdown. I don't want to have to remember the whole markdown syntax.
- eviks 3y ago
  That's indeed backwards (though I'd argue even for non-writers), but then why in your suggested workflow would you use markdown instead of a more efficient and richer document format?
  - Hendrikto 3y ago
    For better diffability, and KISS. No need to go fancy. Fewer possibilities hopefully lead to more consistency.
    - eviks 3y ago
      What is KISS about XML and "more complicated elements" that this editor is doing? Also the land of markdowns is notoriously inconsistent
  - gadders 3y ago
    As the other comment says, for better diffability, but also it's good to store the document in a "neutral" format and then render for the eventual display - MS Word, PDF, HTML. If you store Markdown in a database it would be easier to full text index and update as well EG "We've changed our Product Name to SuperWidget from MidWidget. We need to do a global find and replace on all our docs."
    - eviks 3y ago
      For the writers markdown diffability is bad since it mixes style and content Strange to call markdown neutral given how it's tied to HTML, and that you could just as well convert your "non-neutral" rich format to the same targets How is Markdown _Super_<span style="color:blue">Widget</span> easier to globally find&replace vs. anything else that you create an index for in a database?
martypitt 3y ago
Looking at the website, it seems like it's limited to MD, without support for MDX - which is a shame, as MDX has become a powerful tool in how we write documentation of late -- especially since their output strategy is "click to host this as a website" -- perfect for MDX. Also, it seems even more odd that their markdown support is a custom flavour - adding support for things like tabs, and warning styles. (Unless I've missed something?) It's unhelpful for a WYSIWYG tool to show you something of how it's rendered in a very small subset of the markdown ecosystem.
- azangru 3y ago
  Maybe I am missing something, but how would mdx work? Mdx requires a jsx runtime, plus components written in jsx. How would the writing tool know which runtime/framework to use for jsx components, and where to pull jsx components from?
  - FractalHQ 3y ago
    It could generate a mitosis ast. Then we can have adapters for mdx / mdsvex / whatever the others use!
jerrygoyal 3y ago
obsidian could be one good alternative to this.
GoodDreams 3y ago
I want tested code in my docs. I want my docs’ build to fail if sample code doesn’t actually work.
- elric 3y ago
  We built something like this at my previous employer, on top of asciidoc. With integration tests in both directions: documented code was executed and tested for correctness, and the product build would fail if certain features didn't have corresponding documentation. Automating these things is a pretty easy way of enforcing the availability of documentation. It does nothing to check whether the documentation is half way readable, however ...
Delokoloololo 3y ago
[flagged]
tannhaeuser 3y ago
Seeing a GUI editor for markdown when there's also XML under the hood, I'm expecting it's a matter of time until they "pull a Confluence" and shift away from end-to-end lightweight markup eventually, providing it only at the time of typing as a comfort editing experience or even key binding and convert it into XML immediately. That's because, unlike SGML, its offspring XML lacks (ie. deliberately didn't include for simplicity of implementation) integral support for lightweight markup, to only later re-introduce it, awkwardly or in an ad-hoc or hardcoded fashion. As much as XML might make sense as a canonical profile of SGML for archival or delivery, using is as an authoring format forcing users to dutifully close elements and input other redundant and excessive boilerplate the markup language can figure out itself is brutal and no progress. And has also clearly failed despite decades of forcing it on the web, where SGML remains the only formal markup meta-language capable to describe HTML, even post HTML 4.
- _the_inflator 3y ago
  I had exactly the same thought. Almost everything starts "lightweight", limited, easy to handle and use syntax, short but expressive - until you add feature by feature to it, and voila end up building tools on top of your tool. From a business perspective Jetbrains is doomed to follow this path, since they wanna make money, they have to lure you into their ecosystem and make switching to other solutions as hard as possible. Also they have to add feature by feature just to simulate progress. There is some magic in simply sticking to one system and never change, say MD. It has its limitations, but this is true for everything. JetBrains' tool looks promising, but I fear it will be a creepy mess in 5 years from now.
  - pjmlp 3y ago
    I have seen this movie before, when Borland thought they couldn't go further with Delphi and C++ Builder, bought a company in SDLC/ALM space, and then Imprise came to be. JetBrains trying to go everywhere, and also trying to push Kotlin outside the JVM ecosystem, kind of brings memories back.
qalmakka 3y ago
A "real" LaTeX IDE would be nice. I think not including full integration with LaTeX (which is clunky, full of gnarly to use tools, ...) would help a lot of people writing papers and other similar works.
- gh02t 3y ago
  The LaTeX plugin for Jetbrains IDEs is pretty good for that IMO. Before that I used to use TeXstudio, and I wrote my dissertation with Lervag's vim plugin. Both of which I also like, but the Jetbrains plugin hits my needs and preferences a bit better nowadays as it is something more "IDE" like.
- yencabulator 3y ago
  You might enjoy https://typst.app/ https://typst.app/ The underlying input->PDF toolchain is open source, and very nice: https://github.com/typst/typst https://github.com/typst/typst
pjmlp 3y ago
Doesn't seem to offer any competition to technical writing tooling like Oxygen XML.
wg0 3y ago
If not all, much of it can be done within VSCode's preview pane on Markdown files with right extensions (and probably out of the box as well) so not sure what's the value here or maybe I am not the right target audience for this. What could be interesting is a full featured Open API workbench from JetBrains that has full autocomplete, lets you split files with JSON pointers, allows visually adding documentation, examples, schema and such and not only that, generates a mock server based on API specs all the time from examples and if not from examples then using something like faker or LLM so your API is always GET /api/myendpoint ready, there's no need to "click that button, start a server" thing. It is always on the given endpoint. Swagger Editor and friends are not quite there. Commercial web based offerings are also... not that easy to use. Would love some suggestions if something exists already.
superbaconman 3y ago
Publishing the documentation seems like a lot of work. I guess everything is just manually synced between users via git?
zaps 3y ago
DITA or GTFO
luke-stanley 3y ago
Hmm, if only it supported RST (Restructured Text) like Readthedocs uses. Currently it does not mention it so I assume it has no support. Messing with Sphinx just to update docs can be a pain.
- specialist 3y ago
  I've been trying the misc reStructuredText (RST) extensions for VS Code. Esbonio seems to have the most polish (for now). https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio https://marketplace.visualstudio.com/items?itemName=swyddfa.... It's okay? To my noob eyes, it looks like everyone is using Sphinx for the preview and doc generation. RST has more features, extensibility than Markdown. Probably fine for a website and brief docs? I'm mosdef interested in Writerside. My current FOSS project needs some docs. Good timing for me.
treve 3y ago
Pretty interesting product, but managed to crash it twice in different ways trying to work with some existing content.
Hedgehog52 3y ago
d

265 points by thatxliner 3y ago

Looking at the landing page it appears they are aligning the product with the Diataxis framework (web: Diataxis.fr). I see that as a good thing.

kaycebasques 3y ago
I don't see much to support that claim. Tutorials and references are very common concepts among technical writers, with a history that long predates Diataxis...
- spondylosaurus 3y ago
  Is DITA older than Diataxis? Even if it is, DITA's still far from the first, but you know how they love their topic-based authoring in DITAland....
  - pjmlp 3y ago
    I was using DITA back in 2007 for technical documentation, apparently Diataxis seems quite recent, assuming I have found the right date.

deleted 3y ago

[deleted]

menacingly 3y ago

Generally a big fan of jetbrains, but can't shake that the name sounds like the crime of murdering a writer

rob74 3y ago
Interesting association - but wouldn't that be Writer-cide?
- xwowsersx 3y ago
  Yeah. "sounds like", not "reads like"
gjvc 3y ago
[flagged]

yodon 3y ago

I use SpecFlow (Gherkin for the .NET world), and what I really want is to be able to tie my tutorials to my test cases so I get a CI/CD error if I make a code change that breaks a tutorial or change a tutorial to have instructions that don't actually work.

jw_cook 3y ago

Interesting, that's not what I expected. So it seems like it's an opinionated integration between an editor and a Markdown-based static site generator with its own set of XML-based markup features. Sounds like that has potential. Its docs are quite nice (as I would hope to see from a documentation tool) and a good demo of what it's capable of, but after spending a bit of time looking them over I still have several questions: * How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? * Most people who write a lot of docs are already invested in some documentation toolset or another. What does this tool offer that would make it worthwhile to switch? * From the overview page: "This project developed out of hundreds of customer interviews and 10+ years of working on the IntelliJ Platform documentation. These experiences gave us a long list of features to build and problems to solve." I'd be interested to hear more about specific lessons learned from these interviews and how Writerside addresses them.

spondylosaurus 3y ago
> How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? Looks like this has a GUI, for one, which is potentially a big selling point for the not-so-technical crowd. I know there are headless CMS tools out there that you can hook up to almost any SSG, but even getting that set up is way too big of a stumbling block for the kind of tech writer who doesn't want to tinker or use the CLI or any of that. At that point you'd probably just opt to use Zendesk or whatever (boo). > What does this tool offer that would make it worthwhile to switch? Even with the GUI stuff, I'm also wondering whether there's anything here enticing enough to switch. If your docs are already entrenched in some other ancient tool, it can be hard to get the resources/support to switch even if you want to switch, which many writers may not. OTOH anyone who wants to do docs-as-code probably already is, and the kinds of environments where docs-as-code thrives are the kinds of environments where it's not unreasonable to ask your writers to learn Git.
troupo 3y ago
> How does this compare to other well-established SSGs (Sphinx, Hugo, Jekyll, etc.)? Those are SSGs, not documentation systems. Just because they are used in that way doesn't make them such. > I'd be interested to hear more about specific lessons learned from these interviews and how Writerside addresses them. Some of them are listed on the project's front page

deleted 3y ago

[deleted]

kaycebasques 3y ago

I wonder if JetBrains is going for the professional technical writer (TW) market outside of software development. Think aviation, military, manufacturing, etc. They seem to use paid writing suites quite a lot. MadCap Flare is a name you hear often. TW teams writing in B2C contexts often use these suites too. JetBrains markets it as docs-as-code though, a concept that software-development-focused technical writers would care most about. There is also the angle that a lot of engineers don't want to deal with any bullshit setting up a docs authoring env. If this tool makes it easier for them to contribute docs, I could see that as a way to get solid adoption. The docs quality automation sounds interesting. Couldn't find a link that explains more. (I'm on mobile.) (I've been a TW for ~10 years.)

pbowyer 3y ago
> They seem to use paid writing suites quite a lot. MadCap Flare is a name you hear often. TW teams writing in B2C contexts often use these suites too. I didn't know these suites existed. What other ones are popular, and what's their selling point?
- spondylosaurus 3y ago
  MadCap is the big one I hear about, then maybe FrameMaker at a distant second and plain old Microsoft Word. As a software technical writer who loves docs-as-code I don't know how the writers in manufacturing and aviation and whatnot put up with those tools...
  - mjoneill 3y ago
    MadCap Flare was an awesome product. It grew out of the old BlueSky "RoboHelp" suite (which was also awesome) and could be used to output to many different formats (online help, web help, print docs, confluence). It's been a while, but I think you could even use FrameMaker to author and still use Flare to transform output to all its supported formats. It's been a long time since I immersed myself in this world, so apologies if my memory is less than perfect.
  - mjoneill 3y ago

mikro2nd 3y ago

No Asciidoc? I know (and use daily) the IntelliJ Asciidoc plugin, so it's surprising to me that they make a writing plugin/environment and don't support AD out of the box. eta: Having now had a closer look, some more thoughts: The tool is clearly focussed on writing docs "for a website"; for external consumption. (For whatever value you choose for "external".) Definitely not for internal-to-a-project docs that you'd want side-by-side in a code project[1]. So no wikilinking between pages, which is (for me) a deal-breaker, making this thing basically just a previewing Markdown editor that also does XML source. Well, it's early days, so let's hope that the tool becomes all it might be someday. But if you're doing "for external consumption via a website" docs, then maybe this can be useful to you, though it's hard to see what it's doing that a dozen other previewing Markdown editors don't already do, and some better. [1] Yes, I'm aware that there are several plugins to IJ that do side-by-side note-making in projects. I've tried (probably) all of them, and they're all badly deficient in one way or another.

janosdebugs 3y ago
This. Any time I saw a more complex doc work with several editors and reviewers, it was in Asciidoc.
byb 3y ago
I want to second your comment. AsciiDoc is growing in popularity. A year ago I surveyed a dozen tools and went all in with it. I'd like to see IJ take it a step further beyond AsciiDoc, by supporting Antora to generate and deploy static websites. When combined with Antora-Assembler its also possible to generate PDFs using the ruby-based AsciiDoctor PDF. I'm currently introducing a Docs-as-Code workflow using Visual Studio Code at my organization, because of the very permissive license terms of VSC and the decent AsciiDoc preview function. Mostly though, I find reading adoc files quite easy until lots of Antora snippets (which don't resolve) and conditions start getting added in. A lot of technical writers I've met have had a hard time understanding XML, which is nothing to say of the average office worker who wants to open up their old copy of Office 97 and write a completely unstructed document with a WYSIWIG interface. IJ IDE licenses start to add up, so if IJ is competitive against Oxygen, this might make sense for a lot of organizations to jump over.

eskaytwo 3y ago

If this could generate Confluence that would overlap well for a lot of JetBrains IDE users

martypitt 3y ago
Jetbrains have a pretty decent Knowledge base inside YouTrack (their issue tracker tool)
steamer25 3y ago
Was actually thinking, once you've integrated it with a CI action and cheap static web host, this replaces Confluence in many ways. Looks like the basic editor is and will remain free. This could be a pretty great approach. What should be especially nice is being able to blend automatically-generated documentation and e.g., automated testing reports, etc. in the same host/site as more manually curated documentation. Maybe this would also solve the other problem with Confluence--that people end up using it as a junk drawer. DO NOT PILE YOUR TRANSIENT MEETING NOTES IN THE SAME SPACE AS YOUR TECHNICAL DOCUMENTATION PEOPLE. It fills the search index with noise and makes it impossible to find any information except the stuff that was only relevant for the two days after it was written three years ago. On that note, it seems like the primary downside of this is that you don't get search indexing at all unless you also configure and integrate something like OpenSearch.

ez_mmk 3y ago

If it exists there is a jetbrains tool for it

rob74 3y ago

Markdown and XML are nice, but what about more advanced documentation formats like OpenAPI? For one recent project, I set up automatic generation of the OpenAPI docs from (much more compact and flexible) CUE definitions (https://cuelang.org/ https://cuelang.org/) - which has the bonus of also being able to test the API against the definitions. JetBrains has a CUE plugin, but it's really barebones (doesn't even support jumping from the usage of a schema to its definition). Of course the possibilities when generating docs are endless - just think of the various syntaxes for doc comments, embedding examples/tests in source code etc., and each language tends to have its own standard (either built in or third party).

lananovikova 3y ago
openAPI docs support is mentioned https://www.jetbrains.com/help/writerside/api-documentation.html https://www.jetbrains.com/help/writerside/api-documentation....

gadders 3y ago

Interesting tool, but from the first video on the page it looks like you have to write in markdown and then look at the wysiwyg window to see what your output would be like. That seems backwards to me, if the target is writers. A better tool would let you create in a wysiwyg MS Word-like editor, but save all docs as markdown. I don't want to have to remember the whole markdown syntax.

eviks 3y ago
That's indeed backwards (though I'd argue even for non-writers), but then why in your suggested workflow would you use markdown instead of a more efficient and richer document format?
- Hendrikto 3y ago
  For better diffability, and KISS. No need to go fancy. Fewer possibilities hopefully lead to more consistency.
  - eviks 3y ago
    What is KISS about XML and "more complicated elements" that this editor is doing? Also the land of markdowns is notoriously inconsistent
- gadders 3y ago
  As the other comment says, for better diffability, but also it's good to store the document in a "neutral" format and then render for the eventual display - MS Word, PDF, HTML. If you store Markdown in a database it would be easier to full text index and update as well EG "We've changed our Product Name to SuperWidget from MidWidget. We need to do a global find and replace on all our docs."
  - eviks 3y ago
    For the writers markdown diffability is bad since it mixes style and content Strange to call markdown neutral given how it's tied to HTML, and that you could just as well convert your "non-neutral" rich format to the same targets How is Markdown _Super_<span style="color:blue">Widget</span> easier to globally find&replace vs. anything else that you create an index for in a database?

martypitt 3y ago

Looking at the website, it seems like it's limited to MD, without support for MDX - which is a shame, as MDX has become a powerful tool in how we write documentation of late -- especially since their output strategy is "click to host this as a website" -- perfect for MDX. Also, it seems even more odd that their markdown support is a custom flavour - adding support for things like tabs, and warning styles. (Unless I've missed something?) It's unhelpful for a WYSIWYG tool to show you something of how it's rendered in a very small subset of the markdown ecosystem.

azangru 3y ago
Maybe I am missing something, but how would mdx work? Mdx requires a jsx runtime, plus components written in jsx. How would the writing tool know which runtime/framework to use for jsx components, and where to pull jsx components from?
- FractalHQ 3y ago
  It could generate a mitosis ast. Then we can have adapters for mdx / mdsvex / whatever the others use!

jerrygoyal 3y ago

obsidian could be one good alternative to this.

GoodDreams 3y ago

I want tested code in my docs. I want my docs’ build to fail if sample code doesn’t actually work.

elric 3y ago
We built something like this at my previous employer, on top of asciidoc. With integration tests in both directions: documented code was executed and tested for correctness, and the product build would fail if certain features didn't have corresponding documentation. Automating these things is a pretty easy way of enforcing the availability of documentation. It does nothing to check whether the documentation is half way readable, however ...

Delokoloololo 3y ago

[flagged]

tannhaeuser 3y ago

Seeing a GUI editor for markdown when there's also XML under the hood, I'm expecting it's a matter of time until they "pull a Confluence" and shift away from end-to-end lightweight markup eventually, providing it only at the time of typing as a comfort editing experience or even key binding and convert it into XML immediately. That's because, unlike SGML, its offspring XML lacks (ie. deliberately didn't include for simplicity of implementation) integral support for lightweight markup, to only later re-introduce it, awkwardly or in an ad-hoc or hardcoded fashion. As much as XML might make sense as a canonical profile of SGML for archival or delivery, using is as an authoring format forcing users to dutifully close elements and input other redundant and excessive boilerplate the markup language can figure out itself is brutal and no progress. And has also clearly failed despite decades of forcing it on the web, where SGML remains the only formal markup meta-language capable to describe HTML, even post HTML 4.

_the_inflator 3y ago
I had exactly the same thought. Almost everything starts "lightweight", limited, easy to handle and use syntax, short but expressive - until you add feature by feature to it, and voila end up building tools on top of your tool. From a business perspective Jetbrains is doomed to follow this path, since they wanna make money, they have to lure you into their ecosystem and make switching to other solutions as hard as possible. Also they have to add feature by feature just to simulate progress. There is some magic in simply sticking to one system and never change, say MD. It has its limitations, but this is true for everything. JetBrains' tool looks promising, but I fear it will be a creepy mess in 5 years from now.
- pjmlp 3y ago
  I have seen this movie before, when Borland thought they couldn't go further with Delphi and C++ Builder, bought a company in SDLC/ALM space, and then Imprise came to be. JetBrains trying to go everywhere, and also trying to push Kotlin outside the JVM ecosystem, kind of brings memories back.

qalmakka 3y ago

A "real" LaTeX IDE would be nice. I think not including full integration with LaTeX (which is clunky, full of gnarly to use tools, ...) would help a lot of people writing papers and other similar works.

gh02t 3y ago
The LaTeX plugin for Jetbrains IDEs is pretty good for that IMO. Before that I used to use TeXstudio, and I wrote my dissertation with Lervag's vim plugin. Both of which I also like, but the Jetbrains plugin hits my needs and preferences a bit better nowadays as it is something more "IDE" like.
yencabulator 3y ago
You might enjoy https://typst.app/ https://typst.app/ The underlying input->PDF toolchain is open source, and very nice: https://github.com/typst/typst https://github.com/typst/typst

pjmlp 3y ago

Doesn't seem to offer any competition to technical writing tooling like Oxygen XML.

wg0 3y ago

If not all, much of it can be done within VSCode's preview pane on Markdown files with right extensions (and probably out of the box as well) so not sure what's the value here or maybe I am not the right target audience for this. What could be interesting is a full featured Open API workbench from JetBrains that has full autocomplete, lets you split files with JSON pointers, allows visually adding documentation, examples, schema and such and not only that, generates a mock server based on API specs all the time from examples and if not from examples then using something like faker or LLM so your API is always GET /api/myendpoint ready, there's no need to "click that button, start a server" thing. It is always on the given endpoint. Swagger Editor and friends are not quite there. Commercial web based offerings are also... not that easy to use. Would love some suggestions if something exists already.

superbaconman 3y ago

Publishing the documentation seems like a lot of work. I guess everything is just manually synced between users via git?

zaps 3y ago

DITA or GTFO

luke-stanley 3y ago

Hmm, if only it supported RST (Restructured Text) like Readthedocs uses. Currently it does not mention it so I assume it has no support. Messing with Sphinx just to update docs can be a pain.

specialist 3y ago
I've been trying the misc reStructuredText (RST) extensions for VS Code. Esbonio seems to have the most polish (for now). https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio https://marketplace.visualstudio.com/items?itemName=swyddfa.... It's okay? To my noob eyes, it looks like everyone is using Sphinx for the preview and doc generation. RST has more features, extensibility than Markdown. Probably fine for a website and brief docs? I'm mosdef interested in Writerside. My current FOSS project needs some docs. Good timing for me.

treve 3y ago

Pretty interesting product, but managed to crash it twice in different ways trying to work with some existing content.

Hedgehog52 3y ago