4 ms·
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept
by coldpie 3y ago
Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.
- lukan 3y agoThe arch wiki for example is not perfect, but still helpful to me (and Wikipedia in general). I would not overgeneralize.
- packetlost 3y agoSo what do you use instead?
- kaidon 3y agoA wiki
- bearjaws 3y agoAssign domains of the app to developers, the people doing the code reviews require people to update documentation. Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev. The editing software can be anything really.
- lukan 3y agoAnd ... this can then still be a wiki, right? Not saying that they are the best form, but I think you can combine wikis with people who (have to) take responsibility for certain articles.
- baby_souffle 3y agoI am not OP but I push very hard for docs as code. Your pull request should change content in the ‘src’ folder *and* the ‘docs’ folder. Especially if making changes to the over all architecture or introducing a new dependency! The team shouldn’t let the PR ,edge until the docs are sufficient
- coldpie 3y agoThe same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.
- bmitc 3y agoThis doesn't work for documentation that needs to be viewed by people without source-code control access.
- coldpie 3y agoSure it does. As part of your CI process, build your markdown into HTML or whatever and host it.
- bmitc 3y agoSlack message received: "Hey, I was reading the documentation and walking through the process and encountered this <bug> and this <typo>. Can you fix <this> and re-export the documentation? Thanks!"
- coldpie 3y agoI mean, yeah! That's ideal! If someone doesn't have write access to a repo, then they shouldn't be able to edit the docs for the stuff the repo contains without review either. Just like if they found a bug in the code, they should open a ticket for the problem and the dev responsible for those docs will go fix it.
- sshine 3y agoFor us, documentation lives in Markdown in Rustdoc comments above the things they document. There may be longer write-ups, examples, etc. at the module level. Documentation gets compiled into a docs.rs-style searchable website like so: https://docs.rs/tokio/1.36.0/tokio/ https://docs.rs/tokio/1.36.0/tokio/ Examples are compiled and run as part of the default CI toolchain. So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments. Comments can still get stale because some programmers write but don't read. But they're right there on your screen next to the code you're updating.
- madduci 3y agoSo stop using Confluence?
- eitland 3y agoI think that is a better idea than demanding everyone ditching all wikis. Dokuwiki for example has a sane, plain text format. It can be extended relatively easily compared to Confluence (I have tried both). Unlike certain other wikis it has access control and unlike Confluence you can edit a single paragraph or section at a time. And finally, it is actually a wiki, wiki originally meant "quick" I think and I think calling Confluence a wiki in that context is somewhat ironic.
- bmitc 3y agoThere 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 agoFive 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 agoJust 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 agoSure 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.
- ramses0 3y agoI will counterpoint slightly to this... I'm currently trying to set up a wiki for my house documentation (eg: TechStack, QuarterlyMaintenance, ValuableAssets, BackupRestore, HomeAutomation, etc...). When there's a very limited set of curators, a specific topic, and a self-incentive to keep things "up-to-date" wiki's can be a great choice... mostly as like a knowledge base or internal glossary/dictionary. For true "documentation" (if you don't take the wiki as a whole), and in the corporate world, I agree with the issues against using wiki's.
- wduquette 3y agoThis is my experience as well. I don't say it can't be done, but I've seen this happen multiple times. And with GitHub wikis, in particular, it makes it very hard to have docs tied to specific versions of the software.
- bryanlarsen 3y agoWiki is third-worst. Even worse than wiki is Slack. Even worse than Slack is "ask so-and-so". If you destroy wikis without an alternative, they'll be replaced with one of the worse options.
- breischl 3y agoYou seem to be thinking specifically about documentation for one particular project, eg API docs. And in that context I'd agree. But Wikis are useful for things that are shared, or that are not tied to a particular product, or don't exist in the product yet. eg - "What's the temporary workaround for this bug?" - "How do I get started as a new employee?" - "What information do we need on customer requests?" - "What's the team process for handling escalations?" - "Here's the preliminary design for this new feature" You still need someone to update those docs, but it's nice if, eg, the manager (or product/project manager) who isn't in Git all day can do it easily instead of asking a dev to do it.
- muzani 3y agoI remember an anecdote by Will Wright where he said that in large teams they were spending 3 hours in meetings for every hour of work. Wikis were one fix. Wikis do work for very large user bases, say documenting Stardew Valley mechanics. I think for very large teams, say 50, they start to make sense, especially if you're spending more time in meetings updating everyone than doing work.