3 ms·

There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't alw

by bmitc 3y ago

There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense. For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "global" information, whereas repositories contain local information. Putting information like this into a repo can increase the barrier to keeping the documentation updated and also requires source-code control access to view, which not everyone has or should have to view documentation. In my opinion, a combination of wiki documentation plus documentation within the repository are very good. In addition to that, I often use Google's office suite or Microsoft 365 for working documents, that is documents that need to just be written, get collaborative feedback, shared between external and internal people, etc. Then, once they start to solidify and start to get more atomic updates, it makes sense to move them to the wiki or a Markdown document in a repository.

coldpie 3y ago
Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.
- bmitc 3y ago
  Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized. People's problems with documentation are they don't want to deal with it. It's usually not about the systems used to document things.
  - coldpie 3y ago
    Sure you could re-invent source control, ownership models, bug tracking, change review and merge processes in a wiki. Or you can use the tools that we already have for that. The main point is you need ownership and responsibility. Wikis by design don't have those things, and it shows in how people actually use them. Wiki dumpsters are popular exactly because they let people abdicate responsibility, which means docs are no one's responsibility, because no one likes writing docs.
    - deleted 3y ago
      [deleted]
  - umamike 3y ago
    I like to think of it as a garden, you're continually planting and pruning. When things die you remove them. You do your best to figure out where to plant new things.
lcall 3y ago
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.

by bmitc 3y ago

coldpie 3y ago

Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.

bmitc 3y ago
Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized. People's problems with documentation are they don't want to deal with it. It's usually not about the systems used to document things.
- coldpie 3y ago
  Sure you could re-invent source control, ownership models, bug tracking, change review and merge processes in a wiki. Or you can use the tools that we already have for that. The main point is you need ownership and responsibility. Wikis by design don't have those things, and it shows in how people actually use them. Wiki dumpsters are popular exactly because they let people abdicate responsibility, which means docs are no one's responsibility, because no one likes writing docs.
  - deleted 3y ago
    [deleted]
- umamike 3y ago
  I like to think of it as a garden, you're continually planting and pruning. When things die you remove them. You do your best to figure out where to plant new things.

lcall 3y ago

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.