3 ms·

I slightly disagree on priority. IMHO documentation comes first and that includes design (data structure and algo) decisions as well as managed expectations.

I slightly disagree on priority. IMHO documentation comes first and that includes design (data structure and algo) decisions as well as managed expectations. We all want to code. But the fact is - if we want to code correctly we need to write down and manage expectations with both our customers and ourselves. (IE: “self documenting” code is one thing but stuff like “date display format” needs to be somewhere other than in a SimpleDateFormat line and if the customer/design team pivots, docs need updating first to drive the coverage in gaps.)

nailer 4y ago
> if we want to code correctly we need to write down and manage expectations with both our customers and ourselves. Sure, the expectations come from code - types `Record<string, Banana>`, variable names `bananasByID`, etc. rather than some non-machine readable format. > date display format” needs to be somewhere other than in a SimpleDateFormat line The documentation I would have for this (for, say Swift/Kotlin/TS devs consuming the date display format) is The date display format is taken from the Java SimpleDateFormat using "EEE, d MMM yyyy HH:mm:ss Z", see https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html
- flandish 4y ago
  You’re thinking in a silo’d/tunnel vision manner. Consider different audiences. Devs, customer/user, support, sales. Yes, api definitions are in code, but what our customers see is just as valuable. If it’s not what they want, and they can’t support themselves with the doc we write we’ll be in a hellish back and forth with them. Code is our love, and code can be GREAT at documenting itself.. but customers don’t ever want to view javadocs.
  - nailer 4y ago
    > if we want to code correctly we need to write down and manage expectations with both our customers and ourselves I am assuming an audience of devs and customers / users of an SDK - ie people that need to understand the code. Support and sales (unless selling an SDK) should not see any code or code documentation at all.
    - flandish 4y ago
      I am not sure of your experience or industry but while it is true customers/users don’t see code, they most *certainly* see documentation. In the form of “help->about” or user manuals, websites, or call center interaction. When I said “documentation is important” I meant all documentation and sometimes an engineer needs to document across scope boundaries. (IE: you should be able to describe where that file export api fits into the grand scheme in a way that gives a user what they -need- to know or gives support advice on how to fix issues.)
      - nailer 4y ago
        > I meant all documentation OK I thought we were discussing code documentation. I think we see eye to eye on other types of docs.
GuB-42 4y ago
If documentation is how you get your data and code correct, than sure, it is important. But that's a methodology, a mean to an end. There are other methodologies that are not based on documentation, most notably, Agile. But let's imagine. You use your documentation-centric methodology, and produce software, with good data structures, algorithms, and documentation. Problem is, your server room is on fire and so are all your backups, you can still recover some data but it may fail at any time, what will you try to recover first? I don't know about you, but for me, it definitely won't be the documentation (unless they are legal documents, maybe). If I lose the data and code, I will be left with nothing workable, I will have to do everything all over again, not from scratch because of the good documentation, but in the meantime nothing. If I lose only the documentation, future teams will have a hard time reverse engineering the code and all that, but in the meantime, they will still have a working product, and will still be able to do minor evolutions and bug fixes without too much trouble. That's what I mean when I am saying that documentation is the least important. It means the least important as a product, it does not mean it is the least important to your methodology, or that you should not write it first, especially if you use it as a working document to make sure you get the other parts right.
- flandish 4y ago
  Agile is a philosophy and methodology, documentation is a component/facet of what eventually gets created by our work, no? I get what you mean now re: “important” though, I appreciate your reply!
  - GuB-42 4y ago
    Thank you. For once, Agile is actually quite explicit about documentation. From the Agile Manifesto. - Individuals and interactions over processes and tools - Working software over comprehensive documentation - Customer collaboration over contract negotiation - Responding to change over following a plan
    - macintux 4y ago
      Over “comprehensive” documentation, sure. But how much time is lost because the documentation isn’t available that would explain why the code is doing what it’s doing, or worse why different code wasn’t used? There’s a balance.
drbojingle 4y ago
Documentation describing whats already their and why, or documentation describing what's suppose to be there and why? Or both?
- flandish 4y ago
  Both, in my opinion. From incipient need (rfc, etc) to use-cases, to design specifications, tolerance acceptances, expectation management, support, and finally sunset/archival. If the code is where the “why” is found, those who are the end goal consumers of the product will be frustrated, for a small example.

nailer 4y ago

> if we want to code correctly we need to write down and manage expectations with both our customers and ourselves. Sure, the expectations come from code - types `Record<string, Banana>`, variable names `bananasByID`, etc. rather than some non-machine readable format. > date display format” needs to be somewhere other than in a SimpleDateFormat line The documentation I would have for this (for, say Swift/Kotlin/TS devs consuming the date display format) is The date display format is taken from the Java SimpleDateFormat using "EEE, d MMM yyyy HH:mm:ss Z", see https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

flandish 4y ago
You’re thinking in a silo’d/tunnel vision manner. Consider different audiences. Devs, customer/user, support, sales. Yes, api definitions are in code, but what our customers see is just as valuable. If it’s not what they want, and they can’t support themselves with the doc we write we’ll be in a hellish back and forth with them. Code is our love, and code can be GREAT at documenting itself.. but customers don’t ever want to view javadocs.
- nailer 4y ago
  > if we want to code correctly we need to write down and manage expectations with both our customers and ourselves I am assuming an audience of devs and customers / users of an SDK - ie people that need to understand the code. Support and sales (unless selling an SDK) should not see any code or code documentation at all.
  - flandish 4y ago
    I am not sure of your experience or industry but while it is true customers/users don’t see code, they most *certainly* see documentation. In the form of “help->about” or user manuals, websites, or call center interaction. When I said “documentation is important” I meant all documentation and sometimes an engineer needs to document across scope boundaries. (IE: you should be able to describe where that file export api fits into the grand scheme in a way that gives a user what they -need- to know or gives support advice on how to fix issues.)
    - nailer 4y ago
      > I meant all documentation OK I thought we were discussing code documentation. I think we see eye to eye on other types of docs.

GuB-42 4y ago

If documentation is how you get your data and code correct, than sure, it is important. But that's a methodology, a mean to an end. There are other methodologies that are not based on documentation, most notably, Agile. But let's imagine. You use your documentation-centric methodology, and produce software, with good data structures, algorithms, and documentation. Problem is, your server room is on fire and so are all your backups, you can still recover some data but it may fail at any time, what will you try to recover first? I don't know about you, but for me, it definitely won't be the documentation (unless they are legal documents, maybe). If I lose the data and code, I will be left with nothing workable, I will have to do everything all over again, not from scratch because of the good documentation, but in the meantime nothing. If I lose only the documentation, future teams will have a hard time reverse engineering the code and all that, but in the meantime, they will still have a working product, and will still be able to do minor evolutions and bug fixes without too much trouble. That's what I mean when I am saying that documentation is the least important. It means the least important as a product, it does not mean it is the least important to your methodology, or that you should not write it first, especially if you use it as a working document to make sure you get the other parts right.

flandish 4y ago
Agile is a philosophy and methodology, documentation is a component/facet of what eventually gets created by our work, no? I get what you mean now re: “important” though, I appreciate your reply!
- GuB-42 4y ago
  Thank you. For once, Agile is actually quite explicit about documentation. From the Agile Manifesto. - Individuals and interactions over processes and tools - Working software over comprehensive documentation - Customer collaboration over contract negotiation - Responding to change over following a plan
  - macintux 4y ago
    Over “comprehensive” documentation, sure. But how much time is lost because the documentation isn’t available that would explain why the code is doing what it’s doing, or worse why different code wasn’t used? There’s a balance.

drbojingle 4y ago

Documentation describing whats already their and why, or documentation describing what's suppose to be there and why? Or both?

flandish 4y ago
Both, in my opinion. From incipient need (rfc, etc) to use-cases, to design specifications, tolerance acceptances, expectation management, support, and finally sunset/archival. If the code is where the “why” is found, those who are the end goal consumers of the product will be frustrated, for a small example.