As product/engineering teams we tend to generate a trove of text, ranging from architecture documentation, request for comments, product requirement document and more...
Do you use Wikis (and which ones)? Something else?
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.
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? We'd love to follow up on it. Thanks!
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 :-)
