Get the top HN stories in your inbox every day.
kaycebasques
mkl
There's more about the quality features at https://www.jetbrains.com/help/writerside/inspectopedia.html and a little at https://www.jetbrains.com/help/writerside/documentation-qual....
pjmlp
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.
kaycebasques
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.
pbowyer
> 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?
mjoneill
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.
spondylosaurus
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
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
BTW: If you want to connect, there's a professional society for the discipline: Society for Technical Communication (STC).
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.
zapperdulchen
There's a whole niche: DITA CCMS like Tridion or Ixiasoft. Or more pragmatic European CCMS solutions such as SCHEMA ST4, Cosima, TIM-RS or Paligo.
ReleaseCandidat
Our in-house translators use Trados
petepete
Ah, Trados.
I love how on their homepage there's a 1m20s video that shows not a single shot of the godawful UI.
jjice
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.
datadrivenangel
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.
Iterate until this becomes second nature.
kaycebasques
Hi, I have two suggestions.
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.
[1] https://developers.google.com/tech-writing/one
[2] https://www.amazon.com/Writers-Reference-Diana-Hacker/dp/131...
[3] https://www.amazon.com/Docs-Developers-Engineers-Technical-W...
Titiriti59nj
> 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!
applied_heat
Enjoy your airplane flights where all the pilot manuals and checklists are written by AI
mjoneill
> 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....
jw_cook
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
> 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
> 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
mikro2nd
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.
byb
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.
jddj
Does the asciidoc to pdf workflow involve an intermediate html / headless chromium step?
byb
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/
janosdebugs
This. Any time I saw a more complex doc work with several editors and reviewers, it was in Asciidoc.
tannhaeuser
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
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
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.
wg0
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.
yodon
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.
menacingly
Generally a big fan of jetbrains, but can't shake that the name sounds like the crime of murdering a writer
rob74
Interesting association - but wouldn't that be Writer-cide?
xwowsersx
Yeah. "sounds like", not "reads like"
gjvc
[flagged]
rob74
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).
lananovikova
openAPI docs support is mentioned https://www.jetbrains.com/help/writerside/api-documentation....
qalmakka
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
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
You might enjoy https://typst.app/
The underlying input->PDF toolchain is open source, and very nice: https://github.com/typst/typst
luke-stanley
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
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....
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.
gadders
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
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?
gadders
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
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?
AceyMan
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
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
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
I was using DITA back in 2007 for technical documentation, apparently Diataxis seems quite recent, assuming I have found the right date.
Get the top HN stories in your inbox every day.
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.)