8 ms·

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

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 extremely interested in the idea that documentation should be moved to the top of the priority list and, rather than being a duplicative post-processing step, should be the "ground-truth" for generating lots of the follow on artifacts. For example, write API documentation first and use that to generate client side libraries, an API test suite, and server boiler plate code/skeleton. In my search for existing projects and approaches, I came across many interesting things. Swagger: https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger API Doc: http://apidoc.me/doc/gettingStarted http://apidoc.me/doc/gettingStarted Slate: https://github.com/tripit/slate https://github.com/tripit/slate Write the Docs: http://docs.writethedocs.org/ http://docs.writethedocs.org/ It was very interesting to read this GitHub post because they presented yet another approach to treating documentation as a first class citizen with different methods to write docs, host docs, and keep the docs updated. I recently updated the API docs at my workplace to use the Slate tool I referenced above. We manually write docs in a Markdown file, manually use Slate to compile the MD file into HTML, and then manually deploy it to our host. This is approach is incredibly basic and non-scalable, but is light years better than what we had previously, which was API docs directly in the repo's README file. I hope to learn more about the projects listed above (and many others!) as I explore different approaches for treating docs as a first class citizen and pick the approach which meets the requirements of my current team. [EDIT] I am also anxiously awaiting a beta invite for http://readthedocs.com http://readthedocs.com

codezero 12y ago
You may also want to check out Readme: https://readme.io/ https://readme.io/
- conorgil145 12y ago
  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.
  - gkoberger 12y ago
    We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!
    - conorgil145 12y ago
      Thanks for the info! I have many questions about your tool, but if the answer is "go check it out via a free account!" then just tell me that and I'll get around to it :) - Were you influenced by Swagger at all? Did you exist before/after? - Do you expose any schema that developers can modify via an API or similar? Do you have an internal schema that all docs follow? - I edited my original comment to include Read the Docs [1]. Are you familiar with that service (it is in private beta)? What are some advantages of using ReadMe instead of Read the Docs? [1] http://readthedocs.com http://readthedocs.com
  - gkoberger 12y ago
    @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 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.
    - conorgil145 12y ago
forsaken 12y ago
Another option is Read the Docs, which is how we host the Write the Docs docs: http://docs.readthedocs.org/en/latest/ http://docs.readthedocs.org/en/latest/ -- It's basically the above workflow that GitHub describes, but with Sphinx (http://sphinx-doc.org/ http://sphinx-doc.org/) -- which is a mature and powerful documentation system.
- conorgil145 12y ago
  I forgot to mention that, but it is already on my list of things to investigate. I came across readthedocs.com in the last few months (probably on HN) and sent a passionate email requesting access to the private beta. I haven't been selected yet, but I am anxiously waiting to try it out. How would you say that readthedocs.com differs from the tool mentioned in a sibling comment (Readme: https://readme.io/ https://readme.io/)?
lapfi 12y ago
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 tests they can't get out of sync. The example output that gets written to the docs comes from the application so it can't be wrong. And if a test fails, documentation doesn't get written. It also forces you to write tests which is a good thing. If you don't, you don't have docs. I don't know if there are tools like this. I created one for Ruby/Rack apps that I have used in some of my projects. I think this approach works pretty well.
- gjtorikian 12y ago
  I wholeheartedly agree with everything above. Two additional and related thoughts: 1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92aefec0774844c9d4fa4993307e/src/parser.coffee#L300-L302 https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed. 2. Right now, we're exploring into working with JSON schema as a means of providing both testing validation and accurate documentation. If the schema says "This REST method expects a parameter of this type," it becomes very easy to write a test to enforce that behavior; documentation can be easily generated from it; and of course your production code is safer for it. I'm a huge fan of introducing more cross-overs between testing and documentation. I think a lot of time is spent on "clever" (and subjective) validations like http://www.hemingwayapp.com/ http://www.hemingwayapp.com/, but not enough time is spent on basic content checks. It's very easy to drift code, tests, and docs apart. We need to start thinking about all three of them working together.
  - conorgil145 12y ago
    I could not agree more strongly that working on code, docs, and tests as a single unit is an excellent approach to development. I think the best way to convince most developers of doing this is to create tools which make it as automated as possible. If using a tool actually makes their lives easier to accomplish something they already do (write tests? write docs?) and they get the other for free, then that is a huge selling point. I had a similar idea about using JSON Schema to validate my API. However, a few issues that I thought of and a few I discovered while researching: 1) I am not aware of a decent JSON Schema editor. It has been on my wishlist/TODO list for a looong time to write one myself which has similar capability to something like Oxygen for XML [1], but I have not had the time. Do you plan to write and update the JSON Schema by hand? 2) I have not researched them in great detail yet, but Swagger [2] and API Doc [3] seem to have already defined something similar to what I had in mind with JSON Schema. Have you looked into those tools yet? [1] http://www.oxygenxml.com/index.html http://www.oxygenxml.com/index.html [2] https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger [3] http://apidoc.me/doc/gettingStarted http://apidoc.me/doc/gettingStarted
rpgmaker 12y ago
Whatever happened to that "git-based" document format Linus said he was going to work on?
NhanH 12y ago
Isn't what you describe (documentation first, then code) basically a poor man version of literate programming ;) ?
- conorgil145 12y ago
  I wasn't familiar with the term, but a quick search reveals Literate Programming on Wikipedia [1]. I assume that is what you were referencing. I skimmed the summary of the article and it sounds interesting (and similar to what I'm describing). [1] https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
crdoconnor 12y ago
>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 extremely interested in the idea that documentation should be moved to the top of the priority list and, rather than being a duplicative post-processing step, should be the "ground-truth" for generating lots of the follow on artifacts. For example, write API documentation first and use that to generate client side libraries, an API test suite, and server boiler plate code/skeleton. I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works. The number one thing on my wishlist for any project's documentation is simply a glossary, which is trivial to create but is almost never done. Virtually every project has special terms for artefacts, usage, features, etc. which are burned into developers' skulls so deeply that they often forget that outsiders do not use this special terminology. It gets worse when multiple terms refer to the same thing and the same terms refer to multiple (often ever so slightly different) things. No fancy technology needed to write one of these things either. A simple text file will do. The other thing that bugs me is how much documentation is simply describing code that should exist but doesn't. Scripts to build a project or deploy it, for instance. Or mindless test scripts.
- conorgil145 12y ago
  > I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works. Yes 1000x. One of the first things I do when evaluating a new project is read the docs and tutorials. A glossary for each project would also be super useful. I have also run into the issues that you outline (one term to many definitions and vice versa). Do you think the glossary would help solve that by forcing folks to rename things to have clearer terms (if one is already used in the glossary, for example) or do you think that it is just a barrier for some developers to even create the glossary in the first place (out of sight, out of mind mentality). Would you keep the glossary in git (or similar) so that it versions along with the code? It could be a required part of a code review to make sure that reasonable terms and/or acronyms introduced in a PR are added to the glossary.
zeroDivisible 12y ago
If you like swagger, I'd also check RAML - http://raml.org/ http://raml.org/ I found it recently, but it looks quite interesting.
- conorgil145 12y ago
  Thanks for suggesting this. I glanced over the home page and I am definitely adding it to my list of projects to explore. It claims to support many of the features that I am looking for and it will be fun to kick the tires!

codezero 12y ago

You may also want to check out Readme: https://readme.io/ https://readme.io/

conorgil145 12y ago
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.
- gkoberger 12y ago
  We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!
  - conorgil145 12y ago
    Thanks for the info! I have many questions about your tool, but if the answer is "go check it out via a free account!" then just tell me that and I'll get around to it :) - Were you influenced by Swagger at all? Did you exist before/after? - Do you expose any schema that developers can modify via an API or similar? Do you have an internal schema that all docs follow? - I edited my original comment to include Read the Docs [1]. Are you familiar with that service (it is in private beta)? What are some advantages of using ReadMe instead of Read the Docs? [1] http://readthedocs.com http://readthedocs.com
- gkoberger 12y ago
  @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 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.
  - conorgil145 12y ago

forsaken 12y ago

Another option is Read the Docs, which is how we host the Write the Docs docs: http://docs.readthedocs.org/en/latest/ http://docs.readthedocs.org/en/latest/ -- It's basically the above workflow that GitHub describes, but with Sphinx (http://sphinx-doc.org/ http://sphinx-doc.org/) -- which is a mature and powerful documentation system.

conorgil145 12y ago
I forgot to mention that, but it is already on my list of things to investigate. I came across readthedocs.com in the last few months (probably on HN) and sent a passionate email requesting access to the private beta. I haven't been selected yet, but I am anxiously waiting to try it out. How would you say that readthedocs.com differs from the tool mentioned in a sibling comment (Readme: https://readme.io/ https://readme.io/)?

lapfi 12y ago

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 tests they can't get out of sync. The example output that gets written to the docs comes from the application so it can't be wrong. And if a test fails, documentation doesn't get written. It also forces you to write tests which is a good thing. If you don't, you don't have docs. I don't know if there are tools like this. I created one for Ruby/Rack apps that I have used in some of my projects. I think this approach works pretty well.

gjtorikian 12y ago
I wholeheartedly agree with everything above. Two additional and related thoughts: 1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92aefec0774844c9d4fa4993307e/src/parser.coffee#L300-L302 https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed. 2. Right now, we're exploring into working with JSON schema as a means of providing both testing validation and accurate documentation. If the schema says "This REST method expects a parameter of this type," it becomes very easy to write a test to enforce that behavior; documentation can be easily generated from it; and of course your production code is safer for it. I'm a huge fan of introducing more cross-overs between testing and documentation. I think a lot of time is spent on "clever" (and subjective) validations like http://www.hemingwayapp.com/ http://www.hemingwayapp.com/, but not enough time is spent on basic content checks. It's very easy to drift code, tests, and docs apart. We need to start thinking about all three of them working together.
- conorgil145 12y ago
  I could not agree more strongly that working on code, docs, and tests as a single unit is an excellent approach to development. I think the best way to convince most developers of doing this is to create tools which make it as automated as possible. If using a tool actually makes their lives easier to accomplish something they already do (write tests? write docs?) and they get the other for free, then that is a huge selling point. I had a similar idea about using JSON Schema to validate my API. However, a few issues that I thought of and a few I discovered while researching: 1) I am not aware of a decent JSON Schema editor. It has been on my wishlist/TODO list for a looong time to write one myself which has similar capability to something like Oxygen for XML [1], but I have not had the time. Do you plan to write and update the JSON Schema by hand? 2) I have not researched them in great detail yet, but Swagger [2] and API Doc [3] seem to have already defined something similar to what I had in mind with JSON Schema. Have you looked into those tools yet? [1] http://www.oxygenxml.com/index.html http://www.oxygenxml.com/index.html [2] https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger [3] http://apidoc.me/doc/gettingStarted http://apidoc.me/doc/gettingStarted

rpgmaker 12y ago

Whatever happened to that "git-based" document format Linus said he was going to work on?

NhanH 12y ago

Isn't what you describe (documentation first, then code) basically a poor man version of literate programming ;) ?

conorgil145 12y ago
I wasn't familiar with the term, but a quick search reveals Literate Programming on Wikipedia [1]. I assume that is what you were referencing. I skimmed the summary of the article and it sounds interesting (and similar to what I'm describing). [1] https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming

crdoconnor 12y ago

>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 extremely interested in the idea that documentation should be moved to the top of the priority list and, rather than being a duplicative post-processing step, should be the "ground-truth" for generating lots of the follow on artifacts. For example, write API documentation first and use that to generate client side libraries, an API test suite, and server boiler plate code/skeleton. I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works. The number one thing on my wishlist for any project's documentation is simply a glossary, which is trivial to create but is almost never done. Virtually every project has special terms for artefacts, usage, features, etc. which are burned into developers' skulls so deeply that they often forget that outsiders do not use this special terminology. It gets worse when multiple terms refer to the same thing and the same terms refer to multiple (often ever so slightly different) things. No fancy technology needed to write one of these things either. A simple text file will do. The other thing that bugs me is how much documentation is simply describing code that should exist but doesn't. Scripts to build a project or deploy it, for instance. Or mindless test scripts.

conorgil145 12y ago
> I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works. Yes 1000x. One of the first things I do when evaluating a new project is read the docs and tutorials. A glossary for each project would also be super useful. I have also run into the issues that you outline (one term to many definitions and vice versa). Do you think the glossary would help solve that by forcing folks to rename things to have clearer terms (if one is already used in the glossary, for example) or do you think that it is just a barrier for some developers to even create the glossary in the first place (out of sight, out of mind mentality). Would you keep the glossary in git (or similar) so that it versions along with the code? It could be a required part of a code review to make sure that reasonable terms and/or acronyms introduced in a PR are added to the glossary.

zeroDivisible 12y ago

If you like swagger, I'd also check RAML - http://raml.org/ http://raml.org/ I found it recently, but it looks quite interesting.

conorgil145 12y ago
Thanks for suggesting this. I glanced over the home page and I am definitely adding it to my list of projects to explore. It claims to support many of the features that I am looking for and it will be fun to kick the tires!