
Ask HN: What do you use to write your tech docs? - patothon
What do you use to write and collaborate on your technical documentation?<p>As product&#x2F;engineering teams we tend to generate a trove of text, ranging from architecture documentation, request for comments, product requirement document and more...<p>Do you use Wikis (and which ones)? Something else?
======
__d
I've used a bunch of Wikis: GitLab Wiki (pretty awful), GitHub Wiki (same),
Confluence (capable, but tedious), Moinmoin (crufty), and MediaWiki (kinda
over the top).

Confluence's export to PDF is kinda useful: we were able to maintain manuals
that looked acceptable using it.

Other than Wikis, I've used: Texinfo (it has a "look", but is pretty capable),
LaTeX, troff (and nroff), ReST / Sphinx (clunky, but the end result is ok),
DocBook and FOP (for structured docs), Framemaker, Word, and Google Docs.

Things I'd consider when making a choice are the skillset of the authors and
editors; the balance between text and not-text (figures, photos, videos,
whatever) in the content; the required output (PDF? HTML? man pages? Windows
help?); and the toolset support (eg. useful diff and merge tools).

If I had to choose today, I'd probably go with Confluence (largely because the
plugin ecosystem is just so much bigger/better than any of the other Wikis
I've used) for internal or knowledge-base type things, and maybe Sphinx/ReST
for more complex published documents, although I'd likely have a look at
AsciiDoc or something else in that sort of space too. For a seriously large
documentation project, I'd possibly still build a DocBook-based workflow.

~~~
dsumenkovic
Hi, Community Advocate from GitLab here. Thank you for writing about GitLab
Wiki, we appreciate your comment.

Could you please let us know what could make your experience more convenient?
Are there any suggestions you'd like to share? We'd like to hear what made
your hard time using our Wiki.

Feel free to raise an issue or submit a feature proposal over at
[https://gitlab.com/gitlab-org/gitlab-ce/issues](https://gitlab.com/gitlab-
org/gitlab-ce/issues)? We'd love to follow up on it. Thanks!

~~~
__d
Hey .. thanks for the interest!

I guess my expectations are for something approaching competitive with
Confluence (ie. focus on being a great documentation system, not on GitHub
feature parity :-). The real win with Confluence is the plugin ecosystem, and
there's no reason GitLab can't support that too.

One conceptual issue that always bugs me is that a wiki can only exist in the
context of a project: if you want something that's organisation-wide, you seem
to have to create an otherwise-empty project to host it. And then put a
README.md file in the project with a link to the Wiki root, so users can get
there with only two clicks, at least. It'd be great to have a way to have a
first-class Wiki that didn't require this extra hop (I know, it seems trivial,
but I think it matters).

When editing, it's great to have the full-screen option, but without using
that, you have the menu down the left, then a huge gap, and then the editbox,
and then another big white space before the right-hand page edge. Why have
that white space between the sidebar and the text? It just makes you feel
cramped when you're editing. If this is to be a first-class documentation-
production environment, you need to use that space. Yes, you can collapse the
sidebar, but still there's a massive wasted space there.

Page titles don't retain their text casing, which is kinda annoying.

It'd be great to have a way to take a tree of pages, and export that to PDF.
Ideally via some intermediate format, so you could munge it in a CI pipeline
to produce the PDF.

I can't really complain about the Markdown: it's pretty comprehensive. It'd be
great to have a popup cheat-sheet window (not just a link to the doc page) on
the editing page?

To be fair though, this isn't anywhere near enough to justify my "pretty
awful" rating above, is it? I think my problem is mostly that it _feels_
unsatisfying in use. It's not a friction-less experience: it feels like it's a
secondary priority. Which is unfortunate, because it's kinda got the features
to be quite good.

I suspect the problem is that my goal is different: if you want a way to have
some web pages attached to a project, something that is clearly a secondary
feature to the code, and isn't intended to be used for complex document
maintenance, it's probably fine.

I'd like for it to be a way to maintain and produce complex, published
documents with an online editor (so authors/editors don't have to clone, edit
on the desktop and push back).

I'd like to be able to maintain multiple documents in a project.

I'd like to be able to use a CI/CD pipeline to publish the documents (which
could be PDF, or HTML, or EPUB, etc. And have the ability to transform the
intermediate rendered form to add watermarks, headers, footers, indexes,
tables, page numbers, have sequences for eg. numbering figures, etc, etc.

I sort-of imagine something that could reasonably be used to write a book, or
a complex product manual, or a legal document, or something.

If I never had to deal with DOcBook/FOP or Sphinx again, I'd be a happy camper
...

Thanks for asking :-)

