3 ms·

I wish this were an article about some hot new documentation tool instead of another misguided psalm to slack & kanban. Making docs sexy would be a big quality

I wish this were an article about some hot new documentation tool instead of another misguided psalm to slack & kanban. Making docs sexy would be a big quality of life boost for programmers and the people who love them (i.e. project managers and users of software).

hobofan 9y ago
Best tip for docs in small teams: Have a server running in the local network that pulls the latest develop branch, renders it and serves it on the network for each project. For microservices I would recommend API Blueprint, for normal libraries, whatever is the language standard. Really cuts down the friction of getting to the docs, since you don't have to do all those steps on you local machine anymore whenever you need to access the documentation of an internal project. Next best thing would be building Dash docfeeds for internal projects.
- awinter-py 9y ago
  hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program. Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines.
  - hobofan 9y ago
    > I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. > Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines. Could you expand on those points a bit more? As for the first one, it sounds vaguely like https://deckard.ai https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)
    - awinter-py 9y ago
      By 'behavior' I mean two things: (1) contractual behavior (what you want/expect) can be marked up in comments that generate docs but are also readable inline in the code. And (2) actual behavior in the wild from monitoring, tracebacks, profiling. Would be cool if IDEs could drop that next to a function so I can ask 'is this slow', 'does this ever get called'. Re: configuration I'm saying it's not always clear what a config setting does, and esp. how related config settings combine. Having standard types for configuration would let us generate docs for which part of the program are affected by a config setting; at least provide a starting point for understanding the flag's behavior.
  - jacques_chester 9y ago
    Some of my colleagues in Pivotal Labs swear by Spring Cloud Contract[0], but I haven't used it in anger myself. It seems to be what you want -- an independent statement of protocol that's shared between server and client codebases, with code-generation to help each. [0] https://github.com/spring-cloud/spring-cloud-contract https://github.com/spring-cloud/spring-cloud-contract
wpietri 9y ago
I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion. Now documentation is always a last resort for me. That's a shame, as I enjoy writing. Instead I try to put knowledge in existing places, like unit tests, acceptance tests, method names, object names, code structure, file layout, in-app text, and all of the other little things I'm already doing along the way. Only if I can't put something there will I write docs, and then reluctantly and with a feeling I probably missed a chance to minimize duplication. The only documentation I still write without reservation is stuff that obviously doesn't have to keep up with the project as it changes. E.g., personal journals and project blogs are great, in that everybody understands those are out of date right after they're written.
- awinter-py 9y ago
  I agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree with your point about blogposts -- publish date is like a sell-by date, makes it clear when the post has gone stale. Getting insiders to read docs is also hard. Not every piece of code is worth documenting. But I think highly critical and highly reused code is worth documenting, in part for programmers and in part so that non-coder stakeholders can understand the details of the product (i.e. 'sell what you make' if they're on the sales team).
  - dragonwriter 9y ago
    > Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. It's not an impedance mismatch (which results from difference in the structural representations supported by different systems), it's just a content mismatch. And it's not a tooling problem, it's a process problem. Documentation is the single source of truth for intent, and development process must respect that. This becomes more and more important the more people who aren't developers need to understand the logical function of the system.

hobofan 9y ago

Best tip for docs in small teams: Have a server running in the local network that pulls the latest develop branch, renders it and serves it on the network for each project. For microservices I would recommend API Blueprint, for normal libraries, whatever is the language standard. Really cuts down the friction of getting to the docs, since you don't have to do all those steps on you local machine anymore whenever you need to access the documentation of an internal project. Next best thing would be building Dash docfeeds for internal projects.

awinter-py 9y ago
hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program. Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines.
- hobofan 9y ago
  > I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. > Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines. Could you expand on those points a bit more? As for the first one, it sounds vaguely like https://deckard.ai https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)
  - awinter-py 9y ago
    By 'behavior' I mean two things: (1) contractual behavior (what you want/expect) can be marked up in comments that generate docs but are also readable inline in the code. And (2) actual behavior in the wild from monitoring, tracebacks, profiling. Would be cool if IDEs could drop that next to a function so I can ask 'is this slow', 'does this ever get called'. Re: configuration I'm saying it's not always clear what a config setting does, and esp. how related config settings combine. Having standard types for configuration would let us generate docs for which part of the program are affected by a config setting; at least provide a starting point for understanding the flag's behavior.
- jacques_chester 9y ago
  Some of my colleagues in Pivotal Labs swear by Spring Cloud Contract[0], but I haven't used it in anger myself. It seems to be what you want -- an independent statement of protocol that's shared between server and client codebases, with code-generation to help each. [0] https://github.com/spring-cloud/spring-cloud-contract https://github.com/spring-cloud/spring-cloud-contract

wpietri 9y ago

I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion. Now documentation is always a last resort for me. That's a shame, as I enjoy writing. Instead I try to put knowledge in existing places, like unit tests, acceptance tests, method names, object names, code structure, file layout, in-app text, and all of the other little things I'm already doing along the way. Only if I can't put something there will I write docs, and then reluctantly and with a feeling I probably missed a chance to minimize duplication. The only documentation I still write without reservation is stuff that obviously doesn't have to keep up with the project as it changes. E.g., personal journals and project blogs are great, in that everybody understands those are out of date right after they're written.

awinter-py 9y ago
I agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree with your point about blogposts -- publish date is like a sell-by date, makes it clear when the post has gone stale. Getting insiders to read docs is also hard. Not every piece of code is worth documenting. But I think highly critical and highly reused code is worth documenting, in part for programmers and in part so that non-coder stakeholders can understand the details of the product (i.e. 'sell what you make' if they're on the sales team).
- dragonwriter 9y ago
  > Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. It's not an impedance mismatch (which results from difference in the structural representations supported by different systems), it's just a content mismatch. And it's not a tooling problem, it's a process problem. Documentation is the single source of truth for intent, and development process must respect that. This becomes more and more important the more people who aren't developers need to understand the logical function of the system.