Dev guide cleanup

[mtaylor]

As a user I would like concise up to date documentation on how to use Tim

[mtaylor]

Started cleaning up the REST API Documentation. New Guide is here: https://github.com/aeolus-incubator/tim/wiki/api-reference

[jguiditta]

Having all this in the wiki makes it a bit hard to comment on individual elements of the docs as they come up. I really think we should consider doing something where the docs are (perhaps still as markdown, not sure) included in the git repo (say, under a documentation/ dir). Then, if we want to create a github-hosted site for Tim (which I would like us to at some point), all have to to do is point links at these files and we can have easily web-viewable docs, but still get the benefit of reviewing them via pull requests.

That aside, my first comment is on base_images docs. In the import example, would we need to pass in account credentials as well? Can't recall if that is needed for this case or not. If so, that would be good to include in the example.

Main page, Image version section, minor sp mistake, s/guarentee/guarantee (nvm, fixed this and a couple other minor typos-type things right in the wiki page(s)).

Related to image versions - I didn't see this in our roadmap list, but are we still planning to better line this up with IF's BaseImage? Personally, I think this would still be worthwhile even if we did decide to expand support for building by builders aside from IF.

Target Image api - perhaps include how to do 'snapshot style' (since it is mentioned in the overview page on this object)? Though looking at the returned xml, I guess snapshot is actually set on the Provider Image.

Provider Image - might be more clear if we show how to pass in credentials here, even it is just some about how to create a default account object for a given provider, and link to expected format on IF docs. 'We assume you have the correct account relationship created, and that it returns xml as so (link), allowing Factory to build for the correct account'.

Also, a general comment - this looks like it replaces what is in the README, please include that removal (and add links to wiki, or src-controlled documents, if I convinced you to go that route now) as part of this issue.

Those notes and comments aside, this looks good (note that at this point I have only read it, not run through every example to verify it, though the examples look largely unchanged from previous know good state.

[jguiditta]

One other thought - my suggestion about putting the markdown in source control would mostly be a simple copy/paste of what you have already in the wiki pages, and would still render in the github web ui even before we put anything up on the (currently nonexistent) Tim site via github pages. Doing this now would put us in the position to quickly add this documentation to that site whenever we are ready.

[morazi]

Unforunately it doesn't look like GH supports pull requests against the wiki portion of the project. I suppose one could have a process that involved checking out the wiki via git, making changes and sending the patches to the list but that seems to add a fair bit of overhead to the process. If really tight control over the changes is super important maybe that is the best way. If not, maybe a cursory review to get things into the wiki followed by a more formal review of the git commits would work?

[jguiditta]

I think we have agreed to just put the md in src control, then we have it ready to go whenever we want it in gtihub pages site for tim. In the meantime, it can still be referenced from our readme, and viewed easily in the browser

[mtaylor]

Pulling this documentation into a new docs folder.