Infusion Docs for Framework API

[Bates, Simon]

Hi Anastasia,

I'm thinking that I would like to keep hardcoded links out of the source code. I definitely see the benefit of hyperlinks in the Framework API docs but I think it would be better to insert those links into generated HTML with a tool rather than put them directly in the source code.

Specifically, I want to avoid putting links in the source code that take the form of absolute URLs to a specific version of the docs. This seems brittle. However, some sort of linking to the docs that has a more declarative form does seem like a good thing. Such as references to related API functions or doc pages. I would suggest that we do this with some declarative notation that gets turned into a specific hyperlink by the infusion-tags tool as it generates the HTML.

Directing the user to look somewhere without a hyperlink isn't ideal but I am hoping that it is a temporary situation and that we can use tooling in the future to provide links.

Simon

From: Cheetham, Anastasia
Sent: Tuesday, July 08, 2014 9:21 AM
To: Bates, Simon
Cc: fluid-work at fluidproject.org
Subject: Re: Infusion Docs for Framework API


On 2014-07-07, at 3:04 PM, Bates, Simon wrote:


Does directing the user with text and without an automated hyperlink seem like a reasonable initial solution? Please let me know.

It seems reasonable, but I think the text should include an active link to the root of the Infusion Documentation itself. Would that still be too brittle?

--
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocadu.ca<mailto:acheetham at ocadu.ca>           Inclusive Design Institute
                                        OCAD University

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20140708/2e2f9aec/attachment.html>