The 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.
Five years and 80% employee turnover from now, your git docs will be a completely unsearchable pile of outdated trash from employees who don't work there anymore
Throwing your own other comment back at ya :D
If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).
Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!
I agree with you but I also don't see how using source control is a solution to any of it. In my experience, repos go orphan quite regularly in large companies. In the end of the day, documentation requires maintenance.
With that said, there are times where docs in source control are totally viable, especially when their scoped to the repo they are located in.
Slack 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!"
I 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.
Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.
So what do you suggest? Maybe a dedicated technical writing team? But then you might as well just give them responsibility for a wiki, it doesn't have to be a repository.
some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki
This happens if there's docs in a git repo as well.
I 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
And ... 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.
Comments
So what do you use instead?
The 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.
Throwing your own other comment back at ya :D
If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).
Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!
I agree with you but I also don't see how using source control is a solution to any of it. In my experience, repos go orphan quite regularly in large companies. In the end of the day, documentation requires maintenance.
With that said, there are times where docs in source control are totally viable, especially when their scoped to the repo they are located in.
For 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/
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.
Fossil SCM, which comes up on HN every once in a while, rolls a wiki and issue tracker in the same repository as source code.
https://fossil-scm.org
This doesn't work for documentation that needs to be viewed by people without source-code control access.
Sure it does. As part of your CI process, build your markdown into HTML or whatever and host it.
Slack 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!"
I 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.
So in order to find documentation, you need to know which repo to look in?
How do you deal with cross-cutting concerns, docs that span multiple code repositories?
Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.
So what do you suggest? Maybe a dedicated technical writing team? But then you might as well just give them responsibility for a wiki, it doesn't have to be a repository.
This happens if there's docs in a git repo as well.
I 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
Assign 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.
And ... 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.
A wiki