vic-ui
vic-ui copied to clipboard
vmware
Replace hard-coded help URLs in client with doc IDs
Per a discussion with the manager of the vSphere docs, we should preferably not use hard-coded URLs for help links from the client plug-in, due to the ease with which such links can break after the product is released. The solution is to use "info-redirects", about which I know nothing, but I will investigate with the vSphere writers. These info-redirects still need to be updated with every release, to point to the correct version of the doc, but if for any reason doc files move after a release, there is a possibility of the link still working if info-redirects are used.
@cristianfalcone @jak-atx @jooskim we should look into this for 1.4.
Also created https://github.com/vmware/vic-product/issues/1211 to address this in the Getting Started page.
Marking P1 as this seems to be the best way to ensure links are updated to point to 1.4 documentation.
@jooskim apologies for the delay, and thanks for reminding me about this. I have initiated a discussion with our doc tools expert, to see if there is a decent solution for linking to doc content that is outside of our standard DITA-based docs toolchain.
@jooskim and @zjs I have discussed this again with my manager and the doc tools manager and it seems that these famous "info-redirects" are not the best thing to use in our case. The doc tools manager is however working on an automated mechanism for publishing Markdown-sourced docs to https://docs.vmware.com/, which will allow us to publish our final output there instead of on https://vmware.github.io/vic-product/#documentation. The doc source files would remain Markdown, and would continue to live in the Github repo. This mechanism will allow us to use metadata in the Markdown files to identify topics that are linked from the UI. The UI code then uses the doc IDs rather than hard-coded URLs. This mechanism will, unfortunately, not be ready in time for 1.4.
So, for 1.4. we should stick with our current system. I propose that we do keep this issue (which I have re-titled) and use it to implement the doc IDs once we're ready with the Markdown-to-docs.vmware.com publishing mechanism.