Titanium JIRA Archive
Titanium SDK/CLI (TIMOB)

[TIMOB-27790] Docs as Code

GitHub Issuen/a
TypeEpic
PriorityNone
StatusOpen
ResolutionUnresolved
Affected Version/sn/a
Fix Version/sn/a
Componentsn/a
Labelsn/a
ReporterChristopher Williams
AssigneeChristopher Williams
Created2020-03-05T18:44:00.000+0000
Updated2020-03-23T13:47:28.000+0000

Description

We've automated our "legacy" process for publishing docs, which consist of two major doc types: - API Docs - Guides Guides currently come from our Wiki and are published to docs.appcelerator.com (after being exported as HTML and massaged), and we also trigger a wiki crawl from Zoomin to publish the contents to Zoomin/docs.axway.com APIDocs live as xml files in our titanium_mobile repo, and we use custom node scripts to generate jsduck JS files, then run that through a fork of jsduck to generate the docs.appcelerator.com website. Moving forward we'd like to move away from the wiki as source of our Guides content towards markdown files living in a Github repo (probably directly in titanium_mobile?). How can we extract the current wiki contents into markdown? Clean it up? Remove outdated docs? And then how does that get published out to Zoomin? We'd also like to take our API docs and combine efforts with the Dublin team that already published their API docs out. We need to find a way to incorporate multiple products in the same doc website, while hopefully leveraging [~jvennemann]'s work on his prototype: https://appcelerator.github.io/titanium-docs/api/

Comments

  1. Christopher Williams 2020-03-05

    Some follow-up: * The Dublin teams' [docs-as-code site](https://axway-open-docs.netlify.com) *does not* appear to be API docs, but instead equivalent to "Guides", and an email thread more or less states it's equivalent to "staging" and needs to be pushed/synced up to Zoomin/docs.axway.com ** As to how we'd merge in our guides, the [current process](https://axway-open-docs.netlify.com/docs/contribution_guidelines/) means we'd need to host our markdown files in their repo: https://github.com/Axway/axway-open-docs/tree/master/content/en/docs ** This feels a little odd to me that *every* product would have their guides/docs live in this repo, rather than in their own product's repo - but then there's an issue of right to edit the docs versus the src of the product and whether repos are public/private, etc. Maybe it'd make sense for some products like ours to use submodules or push/sync docs between repos? Or maybe we just stick a pointer in our repo to the open-docs repo location where they live? * Most of the actual API docs I can find seem to live under https://docs.axway.com/category/api and are all server-side APIs. ** Most of them use a Swagger UI to show the APIs (see http://apidocs.axway.com/swagger-ui/index.html?productname=transfercft&productversion=3.5&filename=transfercft-swagger-api.json#/) which is obviously geared towards REST server APIs ** AMPLIFY Central DevOps API apparently uses [Stoplight](https://stoplight.io/documentation)
  2. Christopher Williams 2020-03-05

    Potential ways forward: * Do a one-time conversion of our wiki content to markdown files and push to open docs repo ** Confer with their team in advance, ensure that it gets pushed to docs.axway.com/Zoomin ** Modify our doc publishing to use the markdown files as input for guides? (until we can decommission docs.appcelerator.com) ** Take down the wiki * Work out where API docs should live (especially non-server ones like ours!) ** Add to header of Open Docs site?
  3. Christopher Williams 2020-03-09

    https://github.com/Axway/axway-open-docs/pull/472
  4. Christopher Williams 2020-03-13

    https://github.com/Axway/axway-open-docs/pull/489

JSON Source