3 ms·

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

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

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