4 ms·
> I have seen the knowledge inside the company is mostly transferred by talking and hands-on sessions. Yes. Exactly. IMHO this is the factor that's responsible
by scotty79 13y ago
> I have seen the knowledge inside the company is mostly transferred by talking and hands-on sessions.
Yes. Exactly. IMHO this is the factor that's responsible for at least 50% of corporate clumsiness.
> If this would have been my own company there would be tons of wiki pages.
Just having wikis won't help much. I worked at a company that had wiki, people were putting things there as an afterthought. I was total and complete mess. Lot's of information was outdated, duplicated, horribly messy but it still was something. There should probable be some person with sense of structure to prune those pages, nag people about details, construct some sort of tree from these splinters of information.
Corporation also had task tracking system. But it wasn't helping. It was used as afterthought to leave a trace that some work is to be done and some work was done. What's actually to be done was passed via face to face contact. Therefore noone cared about task tracking system and what's written there.
If you want to keep information, you have to use the system that stores it as crucial (only?) communication chanel.
- JonFish85 13y agoWikis 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 agoEvery 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 agoDo 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 agoDepends 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.
- andrewflnr 13y agoI've had this vague idea about what to do if I'm ever in charge of a project. How well would it work to put documentation in with the source, not just doc comments but standalone, and not pass a commit for review unless it has appropriately updated documentation? Maybe an emergency valve for tight deadlines, or turn it off for hotfixes generally. Besides the obvious dependence on some degree of discipline, what are the main problems? I feel like if I actually tried this, it would blow up in some unexpected way.