> major shortcoming is that it’s not accessible enough for non-technical teams to maintain
At the risk of just mirroring my comment above:
Low-level nuts-and-bolts documentation can't be accessible to non-technical people, by nature. Documentation of high-level designs are another matter. Why not use a wiki for the documentation of high-level decision-decisions? A wiki can be accessible to non-technical staff, and it's trivial to link to a wiki page from a comment in source.
It also keeps the source tighter. It negatively impacts readability if the source is full of non-vital comments.
> Why not use a wiki for the documentation of high-level decision-decisions?
Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in. Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.
SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.
> Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge.
High-level project descriptions don't belong in code. It's a different beast, and doesn't belong in the repo alongside the implementation. Non-technical users probably shouldn't even have repo access.
In-code comments, on the other hand, can't reside anywhere else.
> If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in.
They don't need to look. That's what hyperlinks are for.
I'm not sure if you mean end-user here, or the consumer of a library.
If an end-user wants documentation, that means it's high-level documentation, not nuts-and-bolts documentation on the workings of code. A wiki is a fine solution for this. A non-technical end-user has no business exploring the repo.
If it's someone looking into how to use your library, the distinction is still there. If I want to know what Qt is, I look it up on Wikipedia. If I want to learn about a specific concept, I look for a documentation page like this [0]. In neither case would source-code comments be a reasonable choice.
> Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.
Maintaining a stable intranet wiki is no great challenge.
> SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.
For UI reasons I'd go with a wiki over SharePoint, but they're similar in principle: documentation lives in the intranet, each document has a URL, and documents are mutable. They can coexist if they need to: use hyperlinks.
I'm not sure a one-size-fits-all solution is a good idea in the first place. A legal document about a project is going to end up as a .pdf, and doesn't belong on a wiki. On the other hand, technical documentation like [0] should be handled in a 'web-first' way, such as with a wiki.
Perhaps if SharePoint's document-editing were more like a plain old wiki, I could be convinced that it's a reasonable one-size-fits-all solution. (Although in a sense it's doing several things.)
> It's a different beast, and doesn't belong in the repo alongside the implementation.
That's just, like, your opinion, MaxBarraclough. If they aren't in the repo, they're never going to get updated, and as a result they will be outdated within 6 months on any project that's moving anywhere. I prioritize freshness of documentation against most other attributes. It does nobody any good to have documentation for the system as it was 2 years ago.
I take it you agree that high-level documentation shouldn't take the form of comments in source-code.
> If they aren't in the repo, they're never going to get updated
Not so. The Qt folks use a separate repo for their documentation. [0]
My point earlier was that high-level documentation is a separate project than the implementation. You could keep the high-level documentation documents in the same repo as the implementation if you want, that's just a monorepo.
I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform.
Markdown is fine until you realize you would like to have figures, images and tables.
I don't want to spend my time over trite details of a text based markup when I could spend it actually productively.
At that point it's way over easier to use a text processing document of choice (word or open office). I say this as a enthusiast of text based markups over decades from Latex to Markdown.
Wysiwyg document tools aren't applicable to comments in source.
You can't have images in source, but if you really need it you could add an ascii-art-style table. There are tools to generate these, such as https://ozh.github.io/ascii-tables/
There is a reason why everyone uses LaTeX (or similar) when it comes to professional content delivery - it actually saves you time not fighting the editor.
There's no reason why internal readmes should be of 'professional quality'. It's nice, but a low barrier of entry to explain something non-trivial is more important than nice layout, IMO.
Yeah. Except WYSIWYGs take way more time to do anything non-trivial.
This Friday I had spent about 15 minutes trying to put an editor cursor within an empty code block in Confluence. Is that a joke? Do you know how I fixed that? I copied a non-empty block from another paragraph and then edited it.
It would take me or someone else half a second to do that in Markdown/Wiki/LaTeX.
By Wysiwyg I was referring to Word or OpenOffice or Google Docs or whatever the generally used word processing tool in the org is.
It's totally acceptable Confluence at least tries to provide a non-programmer friendly interface for the domain experts who are not necessarily programmers. But it's not acceptable if the gui is broken...
For certain use cases, markdown is arguably the best solution. For a team that uses an SCM like github (or any of the ones that natively render markdown), and that also has simple documentation needs, I can’t imagine a better solution. Markdown is fast to create, can be read rendered or not, can be included in your project repo and in pull requests. Images are easy in markdown, simple tables are easy in markdown (complicated tables very quickly move into don’t bother territory though). It uses the tools and workflow you already have to solve a problem very well.
If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.
Markdown is great, but I’ve seen so much time wasted on Rube Goldberg solutions that would be trivially addressed by using less cool solutions like Word or GDocs.
If the corporate ownership changes, the markdown files will stay. GDocs or Atlassian subscriptions might be ended without migrating the data, leading to loss of key info. Yes it happens!
I like processing the markdown through Jekyll to create a web site that is used by both tech and non-tech. So the site is auto generated from the last change by an engineer.
