3 ms·
It took me a while to work out why this doesn't feel like a full solution. I can imagine it working for simple one-line commands and their switches. I can als
by TheOtherHobbes 8y ago
It took me a while to work out why this doesn't feel like a full solution.
I can imagine it working for simple one-line commands and their switches.
I can also imagine it failing to work for any application that requires multi-line code blocks and/or more detailed how-to examples.
For example - as a hypothetical, imagine you change your API from Oauth to Oauth2, and you have to provide examples of new standard code, perhaps in different languages.
That's very much a how-doc and not a why-doc problem, so supposedly it doesn't belong in the Wiki.
But I really can't see the changes being explainable in a fyi.
Of course you can say "The new code is in repository X instead of X-1." But if there are other questions and fyi's around Oauth2 - and there will be - there's no guarantee that important fact is going to be at the top of the read list.
For complex breaking changes that read list is going to get very long.
Simpler changes are going to have the same issues on a smaller scale.
So this isn't really immutable documentation - it's more of a database-hosted command cheat sheet.
That's a useful thing in itself, but I don't think it's a complete solution for documentation.