6 ms·

Store readme markdown files in the sourcerepo along with the code itself. Make sure during review that changes to code are reflected in the markdown. Doesn't

Store readme markdown files in the sourcerepo along with the code itself. Make sure during review that changes to code are reflected in the markdown. Doesn't need to be exhaustive docs - usually just a high- to medium-level explanation of what why and how goes a long way. Controversial/surprising/confusing choices should be documented in several places - e.g. in the readme, in a bug/ticket, in the check-in comments and also a comment in the code referencing the readme/bug/ticket for more info. Over-communicating the confusing/surprising stuff helps a lot and helps to prevent the "what the hell is this crap? Let's rewrite it" issues since there is a long paper-trail explaining why things were done that way. Putting code comments referencing bugs/tickets etc (ideally with clickable links direct to Jira or whatever - e.g. "// This does <surprising/confusing thing> - see the discussion in http://bug http://bug tracker/12345678" ) means that the trail starts right there in the code, and people have not had to trawl through some nonsense wiki to find the hidden nugget of info (let's face it - we'll read code but hardly ever go out of our way to find and read wikis etc first)

m0zg 7y ago
This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.
- AmericanChopper 7y ago
  I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.
  - fsloth 7y ago
    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.
    - MaxBarraclough 7y ago
      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/ https://ozh.github.io/ascii-tables/
      - fsloth 7y ago
        This was not about inline documentation in source, but about separate readmes. If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.
        heavenlyblue 7y ago
        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.
        fsloth 7y ago
        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. "Everyone" is not using LaTeX.
        heavenlyblue 7y ago
        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.
        7y ago
  - MaxBarraclough 7y ago
    > 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.
    - AmericanChopper 7y ago
      > 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
  - prepend 7y ago
    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.
- MaxBarraclough 7y ago
  > if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef), and use links to wiki pages for descriptions of high-level design decisions?
  - dharmab 7y ago
    This isn't for comments directly on the source code, it's for higher level stuff like "These are the three services that interact to provide such-and-such functionality. Here's their basic architecture, their dependencies and some basic troubleshooting knowledge/tips."
    - MaxBarraclough 7y ago
      Right, but isn't that what I said?
  - m0zg 7y ago
    I meant that I do documentation on the side, not in code. In code, I do human readable comments (using a restricted subset of markdown) where things would otherwise be very difficult to understand. All of this applies uniformly for the code I write for others, as well as code I write for myself.
nelsonic 7y ago
We use the Markdown file method extensively at our company. see: https://github.com/dwyl?&q=learn https://github.com/dwyl?&q=learn But just asking/reminding people to capture learning/knowledge in Markdown is not enough to ensure that it actually happens. If the organisation does not have a learning and sharing culture at all levels having markdown files falls apart quite fast! see: https://en.wikipedia.org/wiki/Learning_organization https://en.wikipedia.org/wiki/Learning_organization People first need to unlearn what they were taught in formal education. In school we are told not to share our homework with others and the mindset of individualism persists in most workplaces. We need a way to measure and reward people for their contribution to the collective knowledge.
- pmontra 7y ago
  Doing homeworks together was ok, sharing answers to tests was not. Anyway, the goal there was to score individual students, the goal here is to build something together. Of course some people want to outshine coworkers or try to become not replaceable, so they won't share anything unless forced. This is probably your point. A way to measure people's contributions could be counting how many times those lines in the wiki were copy pasted to solve problems, but in general it's not easy. We could count commits to markdown but as in code, two lines could be worth more than one hundred.
  - nelsonic 7y ago
    Yeah, agreed. But sharing the answers is exactly what is needed in companies/organisations. I've worked in companies where people hoard data and solutions to problems because it gives them power/influence/job-security. As for tracking commits, if the metric becomes a goal it becomes useless. People will game the system to have more commits, or worse, write a bot to break up their contributions into as many commits as they can get away with. One line can indeed be worth more than 100 if the line fixes helps fix some production bug. The biggest issue I have is people fixing things and not documenting the fix. Our metric of "success" for our shared knowledge is how many people outside of our company/org find our stuff useful. But this is not always possible in secretive or highly competitive industries. Kathy Sierra said "out teach your competitors". https://youtu.be/Dsryx3Ra5pU https://youtu.be/Dsryx3Ra5pU I totally agree with this mindset. https://headrush.typepad.com/creating_passionate_users/2005/09/you_can_outspen.html https://headrush.typepad.com/creating_passionate_users/2005/...
Izkata 7y ago
> with clickable links direct to Jira or whatever - e.g. "// This does <surprising/confusing thing> - see the discussion in http://bug http://bug tracker/12345678" ) That does tend to be a great help if people follow it. One problem though: We're on our 3rd tracker since I started at my job. Lots of knowledge in those old cases disappeared because of it.
- allannienhuis 7y ago
  Keeping read-only archives of the retired bug tracker seems like the right thing to do - even if that had to be done with an external archiving tool (top hit on google: https://www.petekeen.net/archiving-websites-with-wget https://www.petekeen.net/archiving-websites-with-wget)
fsloth 7y ago
I think it's most important that every line changed in production code can be backtracked to a ticket in the "feature management database" whether it's Jira or whatever. This simple rule helps immensely in keeping codebases in good shape. This is the only clearcut rule that I can think of that is obvious and non-negotiable. Other things of course make sense (document something in code, other things somewhere else) but are more matters of taste and culture.
- oneplane 7y ago
  We split it out: non-ticketed changes are recorded by forcing commits with specific commit formatting that puts out a changelog at intervals. That gets you a log of changes that can be either tracked back to a ticket or are self-describing. (public examples are the Angular Commit Message Conventions or the way saltstack uses that stuff https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst https://github.com/saltstack-formulas/.github/blob/master/CO... - you basically enforce some rules using commitlint and record logs using semver, even if you end up not using the versioning for your software)

m0zg 7y ago

This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.

AmericanChopper 7y ago
I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.
- fsloth 7y ago
  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.
  - MaxBarraclough 7y ago
    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/ https://ozh.github.io/ascii-tables/
    - fsloth 7y ago
      This was not about inline documentation in source, but about separate readmes. If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.
      - heavenlyblue 7y ago
        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.
        fsloth 7y ago
        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. "Everyone" is not using LaTeX.
        heavenlyblue 7y ago
        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.
        7y ago
- MaxBarraclough 7y ago
  > 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.
  - AmericanChopper 7y ago
    > 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
- prepend 7y ago
  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.
MaxBarraclough 7y ago
> if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef), and use links to wiki pages for descriptions of high-level design decisions?
- dharmab 7y ago
  This isn't for comments directly on the source code, it's for higher level stuff like "These are the three services that interact to provide such-and-such functionality. Here's their basic architecture, their dependencies and some basic troubleshooting knowledge/tips."
  - MaxBarraclough 7y ago
    Right, but isn't that what I said?
- m0zg 7y ago
  I meant that I do documentation on the side, not in code. In code, I do human readable comments (using a restricted subset of markdown) where things would otherwise be very difficult to understand. All of this applies uniformly for the code I write for others, as well as code I write for myself.

nelsonic 7y ago

We use the Markdown file method extensively at our company. see: https://github.com/dwyl?&q=learn https://github.com/dwyl?&q=learn But just asking/reminding people to capture learning/knowledge in Markdown is not enough to ensure that it actually happens. If the organisation does not have a learning and sharing culture at all levels having markdown files falls apart quite fast! see: https://en.wikipedia.org/wiki/Learning_organization https://en.wikipedia.org/wiki/Learning_organization People first need to unlearn what they were taught in formal education. In school we are told not to share our homework with others and the mindset of individualism persists in most workplaces. We need a way to measure and reward people for their contribution to the collective knowledge.

pmontra 7y ago
Doing homeworks together was ok, sharing answers to tests was not. Anyway, the goal there was to score individual students, the goal here is to build something together. Of course some people want to outshine coworkers or try to become not replaceable, so they won't share anything unless forced. This is probably your point. A way to measure people's contributions could be counting how many times those lines in the wiki were copy pasted to solve problems, but in general it's not easy. We could count commits to markdown but as in code, two lines could be worth more than one hundred.
- nelsonic 7y ago
  Yeah, agreed. But sharing the answers is exactly what is needed in companies/organisations. I've worked in companies where people hoard data and solutions to problems because it gives them power/influence/job-security. As for tracking commits, if the metric becomes a goal it becomes useless. People will game the system to have more commits, or worse, write a bot to break up their contributions into as many commits as they can get away with. One line can indeed be worth more than 100 if the line fixes helps fix some production bug. The biggest issue I have is people fixing things and not documenting the fix. Our metric of "success" for our shared knowledge is how many people outside of our company/org find our stuff useful. But this is not always possible in secretive or highly competitive industries. Kathy Sierra said "out teach your competitors". https://youtu.be/Dsryx3Ra5pU https://youtu.be/Dsryx3Ra5pU I totally agree with this mindset. https://headrush.typepad.com/creating_passionate_users/2005/09/you_can_outspen.html https://headrush.typepad.com/creating_passionate_users/2005/...

Izkata 7y ago

> with clickable links direct to Jira or whatever - e.g. "// This does <surprising/confusing thing> - see the discussion in http://bug http://bug tracker/12345678" ) That does tend to be a great help if people follow it. One problem though: We're on our 3rd tracker since I started at my job. Lots of knowledge in those old cases disappeared because of it.

allannienhuis 7y ago
Keeping read-only archives of the retired bug tracker seems like the right thing to do - even if that had to be done with an external archiving tool (top hit on google: https://www.petekeen.net/archiving-websites-with-wget https://www.petekeen.net/archiving-websites-with-wget)

fsloth 7y ago

I think it's most important that every line changed in production code can be backtracked to a ticket in the "feature management database" whether it's Jira or whatever. This simple rule helps immensely in keeping codebases in good shape. This is the only clearcut rule that I can think of that is obvious and non-negotiable. Other things of course make sense (document something in code, other things somewhere else) but are more matters of taste and culture.

oneplane 7y ago
We split it out: non-ticketed changes are recorded by forcing commits with specific commit formatting that puts out a changelog at intervals. That gets you a log of changes that can be either tracked back to a ticket or are self-describing. (public examples are the Angular Commit Message Conventions or the way saltstack uses that stuff https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst https://github.com/saltstack-formulas/.github/blob/master/CO... - you basically enforce some rules using commitlint and record logs using semver, even if you end up not using the versioning for your software)