4 ms·

Wikis for documentation: great in theory, sucks in practice. Make a change to source, then you have to figure out where the wiki page is for it. Can't find t

Wikis for documentation: great in theory, sucks in practice. Make a change to source, then you have to figure out where the wiki page is for it. Can't find the wiki page? Make a new one. What folder does it go in? Do you make a new folder? What if a page does exist, but it's wrong? Do you fix the whole thing? Just the part you added? Email the person who last updated it? After 6 months it ends up being a tangled mess of insanity, and no one relies on it. You complain about outdated/indescipherable comments? Imagine that multiplied out. In fact, it's almost worse; at least with code you can try to think like a compiler and figure it out. Without code--yikes!

coldtea 13y ago
Every time I see an OSS project use a Wiki for documentation, I run. In the opposite direction. Wiki documentation 99% of time: we have no documentation, nobody cared to write any, and we setup a barebones wiki app in the hope random people can write some documentation for us.
freeman478 13y ago
Do you have any recommendation for documentation then ? In my experience wikis are far from perfect and need regular gardening BUT they are vastly better than a shared folder or a sharepoint with a ton of word documents...
- JonFish85 13y ago
  Depends on the project's scope, who is working on it and also users/usage I'd say. Sometimes embedded documentation can be useful (Doxygen comes to mind). Given a ton of time, it probably should be done in stages, and created starting with the requirements document(s) to at least set the stage for the thought process. There's no blanket right/wrong for all projects. For Microsoft, my guess is that it would make sense to do the inner documentation in much the same way as external documentation is done--people are used to it, the system is already in place somewhere, etc.

4 ms·

Wikis for documentation: great in theory, sucks in practice. Make a change to source, then you have to figure out where the wiki page is for it. Can't find t

by JonFish85 13y ago

coldtea 13y ago
Every time I see an OSS project use a Wiki for documentation, I run. In the opposite direction. Wiki documentation 99% of time: we have no documentation, nobody cared to write any, and we setup a barebones wiki app in the hope random people can write some documentation for us.
freeman478 13y ago
Do you have any recommendation for documentation then ? In my experience wikis are far from perfect and need regular gardening BUT they are vastly better than a shared folder or a sharepoint with a ton of word documents...
- JonFish85 13y ago
  Depends on the project's scope, who is working on it and also users/usage I'd say. Sometimes embedded documentation can be useful (Doxygen comes to mind). Given a ton of time, it probably should be done in stages, and created starting with the requirements document(s) to at least set the stage for the thought process. There's no blanket right/wrong for all projects. For Microsoft, my guess is that it would make sense to do the inner documentation in much the same way as external documentation is done--people are used to it, the system is already in place somewhere, etc.