4 ms·

There is no undocumented open source software, the documentation is just in a technical language. This is why learning to program is important, as it also means

There is no undocumented open source software, the documentation is just in a technical language. This is why learning to program is important, as it also means learning how to read the documentation. I'm not being factious. We always say that documentation doesn't keep up and that the only real documentation is the code. Ultimately the only reliably documented software is free software.

lucaspiller 9y ago
I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important. Unless we start writing paragraphs of comments for every little five line function, there will still be a need for technical documentation outside of code.
- em3rgent0rdr 9y ago
  Well then maybe we all should write enough comments and tests to fully document behavior.
jacobolus 9y ago
Code is the end result of a thinking / problem solving process, not the process itself. If I implement a mathematical formula in code, the “documentation” is the academic paper where the formula is described and proved, and the whole context of textbooks and other papers where the relevant terms are defined and abstractions are constructed, not the handful of lines of abstract arithmetic on one-letter variable names in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting. If you’re going to make such a reductionist definition of “documentation”, why not go all the way: every executable program is just a sequence of clear and simple instructions to the machine. The documentation of what each instruction does is right there in black and white. Why would you need anything else? All programs are documented.
- dungle6 9y ago
  That is indeed the argument and I don't think it is necessarily a bad one. Academic papers are both jargony and written in specialist notation and are not generally accessible to lay people without background in the field. I don't see how it is really much different.
- em3rgent0rdr 9y ago
  Good code can be understood just by reading it. That is practically impossible with binaries.
  - deleted 9y ago
    [deleted]
  - CaptSpify 9y ago
    I think that's kind of jacobolus' point though. (at the risk of speaking for someone else)... jacobolus is saying that in both binary and source format, code is readable. It's just a matter of scale as to how readable each is. Source is an abstraction of the code that is actually running, and documentation should be an abstraction of the source and how the running code works.
- eikenberry 9y ago
  As a firm believer in the old adage that programs are written for people to read, and only incidentally for the machine to execute, I don't buy into this reductionist argument. Code doesn't become self-documenting automatically, writing self-documenting code is one of those things you learn that makes you a good developer. If you throw away your documentation and then can't read the code, you've written bad code.
throwanem 9y ago
You're totally being factious in favor of free software. Not facetious, though, I agree. To your actual point, what hampers free software more than anything imo is a lack of focus on usability. People buy Apple because, less now than a few yeara ago but still the vast majority of the time, it Just Works. People buy Creative Cloud for much the same reason, and Office 365, and whatever other proprietary products you care to name, because they mostly work reliably, and it's not hard to find help when they don't. This is the standard free software needs to meet in order to compete. The reason it doesn't, I think, is because the economic incentive to do so is not there. That's not a problem I know how to solve, and I wish I did, because then I'd be able to advocate free software (and hardware!) for general use, as I would strongly prefer to do. As the matter stands now, though, I can't do so without critically damaging my credibility with those among whom I would so advocate. That's a problem that needs to be solved. How does it become so?
- yoz-y 9y ago
  ElementaryOS seems to be going in the right direction. But I suppose the main "thing that works" is to have a team of people that actually enjoy making software usable by the masses rather than solving X for their own needs.
  - throwanem 9y ago
    That's a rare sort of intrinsic motivation, though, and tends not to last long in the face of frequent contact with users who, having their own situations to deal with, reasonably tend more often to complain about software that fails to make their lives easier than compliment that which does. That's where extrinsic motivation needs to come into play, but it's not much on offer in the context we're considering.
    - em3rgent0rdr 9y ago
      maybe can get doc writers who care more about people rather than things...
- em3rgent0rdr 9y ago
starsinspace 9y ago
Well, in that way, there's no undocumented proprietary software either. The documentation is just in an even more technical language, called machine code.
- pjmlp 9y ago
  The documentation is available in books people are supposed to buy.

lucaspiller 9y ago

I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important. Unless we start writing paragraphs of comments for every little five line function, there will still be a need for technical documentation outside of code.

em3rgent0rdr 9y ago
Well then maybe we all should write enough comments and tests to fully document behavior.

jacobolus 9y ago

Code is the end result of a thinking / problem solving process, not the process itself. If I implement a mathematical formula in code, the “documentation” is the academic paper where the formula is described and proved, and the whole context of textbooks and other papers where the relevant terms are defined and abstractions are constructed, not the handful of lines of abstract arithmetic on one-letter variable names in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting. If you’re going to make such a reductionist definition of “documentation”, why not go all the way: every executable program is just a sequence of clear and simple instructions to the machine. The documentation of what each instruction does is right there in black and white. Why would you need anything else? All programs are documented.

dungle6 9y ago
That is indeed the argument and I don't think it is necessarily a bad one. Academic papers are both jargony and written in specialist notation and are not generally accessible to lay people without background in the field. I don't see how it is really much different.
em3rgent0rdr 9y ago
Good code can be understood just by reading it. That is practically impossible with binaries.
- deleted 9y ago
  [deleted]
- CaptSpify 9y ago
  I think that's kind of jacobolus' point though. (at the risk of speaking for someone else)... jacobolus is saying that in both binary and source format, code is readable. It's just a matter of scale as to how readable each is. Source is an abstraction of the code that is actually running, and documentation should be an abstraction of the source and how the running code works.
eikenberry 9y ago
As a firm believer in the old adage that programs are written for people to read, and only incidentally for the machine to execute, I don't buy into this reductionist argument. Code doesn't become self-documenting automatically, writing self-documenting code is one of those things you learn that makes you a good developer. If you throw away your documentation and then can't read the code, you've written bad code.

throwanem 9y ago

You're totally being factious in favor of free software. Not facetious, though, I agree. To your actual point, what hampers free software more than anything imo is a lack of focus on usability. People buy Apple because, less now than a few yeara ago but still the vast majority of the time, it Just Works. People buy Creative Cloud for much the same reason, and Office 365, and whatever other proprietary products you care to name, because they mostly work reliably, and it's not hard to find help when they don't. This is the standard free software needs to meet in order to compete. The reason it doesn't, I think, is because the economic incentive to do so is not there. That's not a problem I know how to solve, and I wish I did, because then I'd be able to advocate free software (and hardware!) for general use, as I would strongly prefer to do. As the matter stands now, though, I can't do so without critically damaging my credibility with those among whom I would so advocate. That's a problem that needs to be solved. How does it become so?

yoz-y 9y ago
ElementaryOS seems to be going in the right direction. But I suppose the main "thing that works" is to have a team of people that actually enjoy making software usable by the masses rather than solving X for their own needs.
- throwanem 9y ago
  That's a rare sort of intrinsic motivation, though, and tends not to last long in the face of frequent contact with users who, having their own situations to deal with, reasonably tend more often to complain about software that fails to make their lives easier than compliment that which does. That's where extrinsic motivation needs to come into play, but it's not much on offer in the context we're considering.
  - em3rgent0rdr 9y ago
    maybe can get doc writers who care more about people rather than things...
em3rgent0rdr 9y ago

starsinspace 9y ago

Well, in that way, there's no undocumented proprietary software either. The documentation is just in an even more technical language, called machine code.

pjmlp 9y ago
The documentation is available in books people are supposed to buy.