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.)
For that they would need to support DITA and Docbook, which while not fancy around here, I imagine they are pretty much what most of those markets still use.
Markdown for those markets just won't do it.
Tooling like Oxygen XML still seems to be quite common.
The fact they mention XML a few times on the page prompted that idea. But on closer read it seems that they're using XML for some narrow needs and do not plan on general XML-heavy workflows.
> 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?
Def. give a look at DITA...Darwin Information Typing Architecture is not a tool so much as an approach/framework that other products can support. Many modern tooling supports some of the DITA concepts, even if they aren't officially DITA tools.
On the other end, much of documentation has moved into the Wiki space. For a long time, Confluence was making some serious inroads there.
Most professional tooling these days also emphasizes content reuse, and sometimes (if you are lucky) separating content from presentation.
Opinions come from experience: I spent many years in tech writing at both fortune 50's and startups, but have since moved on to other disciplines I enjoy more.
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...
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.
They have local chapters in many geographies. Their annual conference is usually well attended and covers topics related to technical writing from Help Authoring to Content Strategy to Content Marketing to Agile.
More so just a question for you, but how does one get into or at least improve their technical writing as a software engineer? Any feedback? I've found met with questions from customers that my writing wasn't able to make clear and that's something I'd like to work on.
Review every written piece against the goal of the writing. What is the purpose of a document in terms of the reader. What should a reader take away from a paragraph or a sentence.
First, I sense that you should keep work on improving your mastery of English grammar. I have a few resources for that:
* Technical Writing One by Google [1] is a pretty good self-study course for practicing the fundamentals of writing mechanics.
* Find some kind of program that forces you to write and get feedback on your writing. English classes at community colleges, for example. There are probably a lot of online resources, too. The best way to improve your writing is to practice and get feedback; just like the best way to learn about programming is to create programs.
* A Writer's Reference [2] is a canonical reference text for looking up grammar rules.
I know this is boring work but it really is the foundation of communicating clearly.
After you've got those fundamentals down, you'll want to learn about the processes that technical writers follow to figure out what docs customers really need. Docs For Developers [3] is a pretty solid overview of the process that many TWs follow.
> wonder if JetBrains is going for the professional technical writer (TW) market outside of software development. Think aviation, military, manufacturing, etc
Is there a market?
From my experience, professional writers are just low paid freelancers.
Using an free editor, to collect data into AI, to replace them, seems like best business plan!
> from my experience, professional writers are just low paid freelancers
It tends to depend on the company...and what the writers are building, and of course, what the product is. Some products do not lend themselves well to a freelance approach, as the domain and product specific knowledge is quite high. Other products have very specific regulatory compliance obligations that also do not lend themselves readily to freelancing (unless you are talking about long term contractors with 2+ year commitments, etc....
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.
> 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.
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.
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.
In most cases no, AsciiDoctor-PDF converter uses the Ruby library PDF library Prawn to generate PDFs, However, there are alternative PDF converters which do convert from HTML (the VSC AsciiDoctor plug-in allows the option to use a different converter), but I don't think they use chrome. Please note that using different pdf converters is a bit of an advanced topic. https://wkhtmltopdf.org/, and asciidoctor-web-pdf.
https://github.com/ggrossetie/asciidoctor-web-pdf
I encourage everyone to take a look at the documentation; this is the markup language I now use for all my personal and professional projects.
https://docs.asciidoctor.org/
I used the asciidoctor/asciidoctor-pdf program extensively a while ago, and whilst it wasn’t that bad, it was still a bit hacky, didnt support page breaks for example. But maybe it got better now…
The docs call out that page break is supposed to work in PDF, so I guess it should work now? I've found Asciidoctor-pdf to be pretty incredible in the output it produces — only problem is the arcane config file…
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.
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.
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.
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.
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.
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/) - 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).
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.
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.
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.
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.
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?
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."
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?
Yes, those two would work better for the writers since then they'd be able to WYSIWYG-edit individual documents in other editors while having the potentially better style/content diffability/batch renaming etc in this one (and that would also help avoid the common mistake of having two separate views just because the underlying format is plaintexty)
Although personally I hope for a modern rich-text CRDT-based format that would also enable collaboration, but don't know of any specific one in that area
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...
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.
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?
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 ...
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.
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.)