In my experience a wiki is useful to improve the bus count (what happens if key people are hit by a bus). To keep it maintained, establish a culture of using a code review checklist (with things like: does the documentation need to be updated? Is it properly tested? Did the tests fail when the code is intentionally broken or incomplete? Can someone who was not part of the design discussion (nor given any verbal explanation) understand this well enough to maintain it?. Enforce that checklist and improve it (in the same wiki) with time. I think it becomes a big net timesaver and improves quality of life.
Then each team has their own wiki page with a list of "things we care about", each of which links to a separate page that was written using a template of headings, to get minimal (and QUICK TO CREATE) documentation. The template includes about a dozen or less things like: where is the source code, who are the key stakeholders, how do you build it, how & where is it deployed, how are backups done & who is responsible for them, what are the key high-level inputs and outputs, and what else is essential that you want to know, if anything. It is OK to put "N/A" as an answer (if that is true), but all sections are to be completed before it is released.
Those things are separate from the code which is why they are not documented inside the code. They can change even when the code does not, and might sometimes be maintained by non-coders. Code doc comments are more about saying why something was done, in the code, the way it was done.
Then have new people start with the wiki. It should include a section on what to tell new people. This is a potential way to learn, and the new person can have their first task be to update portions of it as they work on new things and work with existing team members. Every attempt to change the culture should be included in the wiki (for example: "we have a rule: no new technical debt. How will we preserve that rule going forward and not just forget like we did in the past? It goes in the wiki and we review it periodically and evaluate how we are doing."). Existing team members should subscribe to change emails so they can verify non-trivial changes!
If there is a QA function, they periodically evaluate (maybe just ask the team) how well the team does at maintaining the wiki pages and following the code review checklist, and reports that to management.
If you don't have people who can or are willing to do that, might be good to ask why, and we all start by looking at ourselves.
Comments
In my experience a wiki is useful to improve the bus count (what happens if key people are hit by a bus). To keep it maintained, establish a culture of using a code review checklist (with things like: does the documentation need to be updated? Is it properly tested? Did the tests fail when the code is intentionally broken or incomplete? Can someone who was not part of the design discussion (nor given any verbal explanation) understand this well enough to maintain it?. Enforce that checklist and improve it (in the same wiki) with time. I think it becomes a big net timesaver and improves quality of life.
Then each team has their own wiki page with a list of "things we care about", each of which links to a separate page that was written using a template of headings, to get minimal (and QUICK TO CREATE) documentation. The template includes about a dozen or less things like: where is the source code, who are the key stakeholders, how do you build it, how & where is it deployed, how are backups done & who is responsible for them, what are the key high-level inputs and outputs, and what else is essential that you want to know, if anything. It is OK to put "N/A" as an answer (if that is true), but all sections are to be completed before it is released.
Those things are separate from the code which is why they are not documented inside the code. They can change even when the code does not, and might sometimes be maintained by non-coders. Code doc comments are more about saying why something was done, in the code, the way it was done.
Then have new people start with the wiki. It should include a section on what to tell new people. This is a potential way to learn, and the new person can have their first task be to update portions of it as they work on new things and work with existing team members. Every attempt to change the culture should be included in the wiki (for example: "we have a rule: no new technical debt. How will we preserve that rule going forward and not just forget like we did in the past? It goes in the wiki and we review it periodically and evaluate how we are doing."). Existing team members should subscribe to change emails so they can verify non-trivial changes!
If there is a QA function, they periodically evaluate (maybe just ask the team) how well the team does at maintaining the wiki pages and following the code review checklist, and reports that to management.
If you don't have people who can or are willing to do that, might be good to ask why, and we all start by looking at ourselves.