Writerside – a new technical writing environment from JetBrains
jetbrains.com
jetbrains.com
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.)
I didn't know these suites existed. What other ones are popular, and what's their selling point?
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.
I love how on their homepage there's a 1m20s video that shows not a single shot of the godawful UI.
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.
Markdown for those markets just won't do it.
Tooling like Oxygen XML still seems to be quite common.
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!
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....
Iterate until this becomes second nature.
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...
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.
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.
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
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'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.
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/
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.
JetBrains trying to go everywhere, and also trying to push Kotlin outside the JVM ecosystem, kind of brings memories back.
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.
The underlying input->PDF toolchain is open source, and very nice: https://github.com/typst/typst
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.
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.
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."
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?
If not markdown, what would you suggest?
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
Not as rich as LaTeX but more powerful than Markdown: .rst and .adoc
I see that as a good thing.
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.
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 ...
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.