4 ms·
> What tools do you use for your writing? > Writers mentioned a number of Open Source options, including Joplin, Asciidoctor and GNU groff. This is a gobsmack
by starkparker 3y ago
> What tools do you use for your writing?
> Writers mentioned a number of Open Source options, including Joplin, Asciidoctor and GNU groff.
This is a gobsmackingly bizarre list. Joplin is a note-taking app, Asciidoctor is a processing/publishing tool for AsciiDoc, and groff is mostly for publishing CLI docs/man pages.
Most technical writers work in either DITA XML, AsciiDoc, reStructured Text, or Markdown. Aside from using oXygen for XML, you're probably in VSCode or some other open-source plain text editor with a plugin to preview the output.
That content often lives in a git repo, or alongside code in a monorepo. It goes through a publishing tool like the DITA Open Toolkit, AsciiDoctor, Sphinx, a static site generator, etc.
Translation typically involves Gettext/Poedit at some point between a variety of frontends, though scaling that is often how tech writing teams wind up going down the DITA XML rabbit hole.
> Lauren Pritchett: "When I was writing more frequently I liked to write in Atom or something like that in Markdown, then put it in a Markdown-to-HTML converter and plop it into Drupal…"
No. No! This is nonsense. In technical docs you absolutely have to have a publishing pipeline that doesn't include a manual copy-paste step into a CMS order to scale. In technical blogs you're authoring closer to the CMS. This makes zero sense.
> I really enjoyed working with LibreOffice because of the ability to create templates, repeat processes, ebooks and cheat sheets…
There are mature and popular open-source tools to do all of those things in AsciiDoc/rST/Markdown that are easier and better at scale than LibreOffice. Even DITA and the DITA-OT can do most of this, though working with XSLTs sucks.
Notably, Pritchett's background is primarily in marketing content, whitepapers, blogging, and traditional book publishing, not product docs: https://hilgspritch.github.io/work.html https://hilgspritch.github.io/work.html
> ... (git and Markdown is) not intuitive, I much prefer Google Docs
If you're doing technical product or dev documentation work, you might be in Google Docs as a bridge with product and marketing, and maybe you legitimately prefer GDocs review tools for editing early drafts of prose.
But if you're writing documentation, then writing docs as code in the same tools and processes ships the docs alongside the implementation. If you can't become competent using git, you're going to struggle mightily in non-marketing tech writing roles.
If you're documenting software, and even if your team isn't writing docs as code, you still need to be able to understand git and fundamental concepts of it well enough to work with the product you're documenting. Your publishing pipeline is probably using a combination of git, CI, and cloud storage, and if your team doesn't have anyone on it who can understand those things then you aren't shipping docs as fast as you could be. Very few non-marketing technical writers make it these days without being competent in git.
-
Also, more generally there's no disclaimer that the moderator of the talk spends a chunk of it talking up a blog that his own consulting company runs and prominently sponsors.
- spondylosaurus 3y ago> Very few non-marketing technical writers make it these days without being competent in git. At least in the software industry, agreed. Not only is it reasonable to expect a TW at an dev-heavy org to familiarize themselves with devs' tools, but it's also damn near impossible to find a good tool for software docs unless you're running your own static site generator. Every premium CMS tool on the market has some kind of dealbreaking fatal flaw... among them their average price, because good luck getting any budget for documentation :P
- MilStdJunkie 3y agoIntroducing Asciidoc to a aerospace team, I was lucky if anyone in the room even knew what git was, let alone how to use it. Every publication system carries with it the paradigm of the industry it's born from, and so-called "docs-as-code" is no different. I still believe that Asciidoc+Version Control+Build Engine of Choice is absolutely the way to pump out complex documentation, but my belief in that fact is probably shaped by the fact I'm at least half programmer myself. When you have an org that doesn't know what merges do, and who absolutely, positively will not review a draft that's not dead tree, the "docs-as-code" approach runs into some real speedbumps, because you have to get all that SME crayon scribble back into the system somehow. It's honestly a problem I still haven't solved yet, in spite of multiple years of effort, to my shame. I just can't see how reviewing a PR is hard, exactly. Like, what part? The part where you see the changes? I dunno. Of course your big ERP vendors will have all the answers here, which is always "Use More Brand X ERP". The secret move is that ERPs come with VP level - and above!! - backing, unlike your Publication System Initiative, which has the backing of maybe a second-tier manager, some PMs, and some burnt out CMS admins.
- shrubble 3y agoJust a note to point out that groff can use different macro sets such as ms or mom and produces decent PDF/PS output (from my limited testing).
- 3x35r22m4u 3y agoThe first time I had contact with a book from O'Reilly was some point in 1997 with their "Running Linux". One of the things that I still reckon is the small section describing the book pipeline, the editor used by the author, typesetting and DTP. IIRC they used Emacs, LaTeX and Quark Xpress. I loved that tidbit.