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 ...
Comments
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 :-)