Establish tidy division between "API Reference" and other "Documentation"

[harry-wood]

Idea: Establish tidy division between "API Reference" and other "Documentation". Have these as top level headings, maybe in a navigation bar near the top of the site. Design inspiration. Something Tom pointed to just now. See the navigation on the Pingdom API docs: https://developer.serverdensity.com/docs [Update: navigation since moved to the top right]

The API Reference is powered by the RAML api-console. The other "documentation" (or we could call it "manual" or something) would be powered by ...something else... (naturally the old clunky 3scale CMS, or wordpress could do it). But "tidy division" means we make some efforts to make the two things look like part of the same website. This is important.

This is a line of thinking I'd forgotten about actually, but I think this idea can alleviate some of the issues with the RAML api-console. I actually started down this route to some extent by labelling the raml output as "API Reference" here.

This goes some way towards tackling a couple of issues:

• https://github.com/transportapi/api-console/issues/8 We'd still have javascript-heavy RAML output, but only for the "API reference" part of the docs. We would aim to have quite a lot of documentation linkable as a classic website (The Pingdom API docs do this. Page re-loads with proper URls in part of the docs. It's seamlessly styled so that you barely notice). I think the raml output would still need work (e.g. https://github.com/transportapi/api-console/issues/6 ) but it becomes less of an issue
• https://github.com/transportapi/api-console/issues/7 The particularly poor UX with the top section of the raml api-console output goes away. We avoid having sections in the top of the raml output. Just stick to endpoint-by-endpoint API reference. This issue https://github.com/transportapi/main/issues/553 goes away too. It's a "hole" in the RAML docs deliberately because it's outside the raml.

[madwort]

I don't think we should be aiming to have a lot of documentation linkable as a classic website, only a few things that don't make sense in RAML. In the example given, the "Documentation" content is a couple of worked examples of using their API and a couple of general comments. It does not duplicate any endpoint docs outside from that which is necessary to get the worked examples going. Ideally they would be slickly integrated in the manner of that example - that's the gold standard I'd like to aim for - but I think this is unrealistic in the short to medium term, and I think we should focus on the content first.