21–30 of 93 posts
I hate it, because it's slow.
but I do see it has some benefits, for example, it automatically generates a content table. so content discovery is easier. it is also designed to be a document system for a software company. you can use it to create meeting notes and tag people.
but overall, I liked mediawiki, the problem with it is, it's hard to make sure things are up-to-date. and it's difficult to do content discovery.
Don't use confluence :( In every team I've been, confluence feels like an huge hole, we can never find what we are looking for...
That's probably because you've used Confluence. If you used something else, then that'd have been the huge hole. Confluence is a very good wiki. There's no wiki that creates good structures for you automagically.
There are various orthogonal concerns to deal with when documenting software development with Confluence:
+ knowing the underlying platforms / technologies your project uses
+ architecture / design of system (which will evolve over releases) -- Gliffy plugin works well for illustrations
+ documenting releases
+ engineering-level precursors to user documentation
+ meetings -- high-level overview of discussions, decisions, resulting actions
+ Confluence wiki integration with bug-tracker, source code repositories
Without an up-front design one will run into problems. Even worse if managing several projects.
We use mediawiki and and recently IT invested in confluence. I hate it, because it's slow. but I do see it has some benefits, for example, it automatically generates a content table. so content discovery is easier. it is also designed to be a document system for a software company. you can use it to create meeting notes and tag people. but overall, I liked mediawiki, the problem with it is, it's hard to make sure thi…
* Super bloated and laggy
* Hard to get your data out/migrate to some rival system. Did your technical writers spend a bunch of time typing strings into a table using the Confluence table building GUI, and now you want that data as a .csv? Too bad, hope you want to spend half an hour in copy-and-paste + reformatting hell.
* Impressively broken search (e.g. if you create a page named "foo" and then search for "foo," you'll often get pages of unrelated results that do not include your page called foo)
* Can't natively show typeset math. Doing so requires plugins that are somehow both expensive, broken, and only compatible with narrow ranges of Confluence versions.
* Gross nonstandard markdown dialect
These are just the shortcomings that I can think of right now. However I think even Confluence is probably better than submitting PR's for docs changes as the OP mentions, since at least it's a wiki.
How? Badly. Right now it's a GitHub wiki in our "infrastructure" repo (which is basically all the bits and pieces that don't fit anywhere and don't have a proper repo of their own). We migrated to this from: "several github wikis, each in the repo of the project" - but often you have overlap and it was bad to find stuff. Pros: - easy backup (git clone) - markdown - easy to get started, "good enough" Meh: - searchable…
Earlier quoted context omitted.
We already have this, the problem is more for processes. Things like "How do I create a build from my commit?". We have dedicated documentation which explains how the build system works in it's entirety as markdown files, but it's painful for a new team member to have to go through that and find out what they need. A simple Q&A document is failing us as well due to the fact that all commits to our main branches need…
Maybe the problem can be reframed? > the problem is more for processes. Things like "How do I create a build from my commit?" With well set up CI and automated builds, would you need this documentation at all? Could other processes which you currently document also be automated? In my (limited) experience there's no great way to handle documentation, apart from reducing the need for it as much as possible. The team I…
We have that. But how would you know that we have that without documentation telling you? How would you know where to find the resulting builds or to check the status?
Earlier quoted context omitted.
We already have this, the problem is more for processes. Things like "How do I create a build from my commit?". We have dedicated documentation which explains how the build system works in it's entirety as markdown files, but it's painful for a new team member to have to go through that and find out what they need. A simple Q&A document is failing us as well due to the fact that all commits to our main branches need…
Why not relax the PR process for the docs directory? If your process is in the way of progress, change the process!
Do not tell them what tool to use, let them own your knowledge base and make their requests for information understood to be P1 priority.
Tangent: I remember the first time I used Quora, thinking that it had a great model of content discovery and collaborative answering — that it would be fantastic if they let companies deploy internal versions of it. Now that Quora has been around for 7 years and has clearly decided not to do this but instead to make money by , does anyone have any guesses as to why they decided not to?