3 ms·

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 e

by hobofan 10y 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 10y 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 10y 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 10y 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 10y 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

by hobofan 10y ago

awinter-py 10y 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 10y 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 10y 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 10y 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