31–40 of 55 posts
Github's convention that web pages for a project are in a different branch of the same project is kind of strange. Also, those things they call "conrefs" are just "macros".
Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref
Earlier quoted context omitted.
I always thought it would be a good idea to generate API documentation from tests. Kind of the same idea you have but the other way around. The problem I used to have is that if you write your documentation by hand it tends to get out of sync with the code. You make a quick change to the code and forget to update the docs. After a while it's a mess unless you stay vigilant. But if you generate documentation from test…
That is an interesting idea. I do like the idea of starting by writing docs because they are very lightweight and it forces you to think through the design of the API. For example, "the params on that route don't look correct" or "this is really difficult to explain, so I think we just over complicated this end point. Let's make it simpler". One could make the TDD argument that writing tests first would accomplish th…
It isn't something I would encourage others to use in its current state, but maybe it will give you some ideas. It uses Ruby's Minitest and adds some syntax to it. When the tests run it captures some things and writes those to an html template.
Earlier quoted context omitted.
You may also want to check out Readme: https://readme.io/
Thanks for suggesting another tool to look into! I only glanced at their homepage, but it looks like they may be using Swagger under the hood because some visual elements are similar and the functionality is also similar. It does appear to have many of the features that I am looking for, so it definitely warrants further investigation.
We existed (much) after Swagger. I've never used Swagger myself, although I briefly played around with the client. Not really that inspired by them.
We use APIDoc (and eventually want to add more) as our "schema", and you can auto-sync from GitHub. Or, you can add it manually.
I am familiar with RTD (moreso the .org version than the .com); they're great. However, they mostly just host Sphinx/markdown/etc files. ReadMe does much more (support section, API explorer, "Suggest Edits", show user keys in the code, etc). If you want to write docs locally and deploy, use RTD. If you want something more full-featured, check out ReadMe.
Earlier quoted context omitted.
Thanks for suggesting another tool to look into! I only glanced at their homepage, but it looks like they may be using Swagger under the hood because some visual elements are similar and the functionality is also similar. It does appear to have many of the features that I am looking for, so it definitely warrants further investigation.
@conorgil145 (Couldn't reply; too nested) We existed (much) after Swagger. I've never used Swagger myself, although I briefly played around with the client. Not really that inspired by them. We use APIDoc (and eventually want to add more) as our "schema", and you can auto-sync from GitHub. Or, you can add it manually. I am familiar with RTD (moreso the .org version than the .com); they're great. However, they mostly…
I came across the APIDoc project when watching an excellent presentation by the Gilt CTO titled "Immutable Infrastructure with Docker and EC2" [1]. It is worth a watch and he mentions that APIDoc allows them to more easily create new micro services in their cluster (of which they have over 300!).
I was reading around the APIDoc site and saw they had a note to investigate Swagger 2.0 to see if it could be useful [2].
[1] https://www.youtube.com/watch?v=GaHzdqFithc [2] https://github.com/gilt/apidoc/blob/master/TODO#L95
I would love to see a few projects explore this concept of generating docs, client code, and server code from a single "ground truth" file and eventually have them all merge into a single defacto standard. That would be exciting indeed (though it seems Swagger may already be approaching that point in some circles).
I'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman ( http://middlemanapp.com ) instead of Jekyll. Middleman has impressive workflows and markdown processing (I'm guessing parallel to that of the Github/Jekyll solution or better). Also conrefs can be implemented by simple partials (which makes less contention for the probably huge conref file) Though I have to b…
I personally found this write up extremely interesting and exciting. I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extrem…
I always thought it would be a good idea to generate API documentation from tests. Kind of the same idea you have but the other way around. The problem I used to have is that if you write your documentation by hand it tends to get out of sync with the code. You make a quick change to the code and forget to update the docs. After a while it's a mess unless you stay vigilant. But if you generate documentation from test…
Maybe an unnecessarily meta example, given that it's the executable documentation/test suite for a testing framework itself. But it's wicked cool!
I personally found this write up extremely interesting and exciting. I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extrem…