4 ms·

> 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 di

> 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.

MaxBarraclough 7y ago
> 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.) [0] https://doc.qt.io/qt-5/layout.html https://doc.qt.io/qt-5/layout.html
- m0zg 7y ago
  > 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.
  - MaxBarraclough 7y 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. [0] https://github.com/qt/qtdoc https://github.com/qt/qtdoc

MaxBarraclough 7y ago

> 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.) [0] https://doc.qt.io/qt-5/layout.html https://doc.qt.io/qt-5/layout.html

m0zg 7y ago
> 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.
- MaxBarraclough 7y 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. [0] https://github.com/qt/qtdoc https://github.com/qt/qtdoc