Stream: implementers
Topic: fhir documentation toolset
Jim Kreth (Aug 09 2017 at 16:47):
I did a search both on this board and the FHIR doc site. I really like the format and content of the FHIR resource documentation (thank you all for the great work on it). I'd like to use the same format for documenting our own services. Can anyone guide me to the toolset / templates used to maintain the resource pages or let me know if they are in anyway proprietary? Thanks in advance...
Lloyd McKenzie (Aug 09 2017 at 17:56):
Hi Jim,
Lloyd McKenzie (Aug 09 2017 at 18:01):
The source for the FHIR specification is freely available from HL7's SVN site (if you don't have a gForge account yet, you can log on as "anonymous" with no password). There's documentation about how to use the build environment here: http://wiki.hl7.org/index.php?title=FHIR_Build_Process. That said, if you're creating specifications based on FHIR, you probably want to use the FHIR IGPublisher. There are a number of implementation guides that provide a look and feel similar to the FHIR spec and can directly consume profiles and other IG materials. We're working on putting together a standard framework for that, but in the meantime, you can look at specifications like the SDC specification https://github.com/HL7/sdc
Jim Kreth (Aug 09 2017 at 18:34):
Thanks Lloyd, I'll dig into these links.
Jayashree Surnar (Aug 10 2017 at 04:30):
@Lloyd McKenzie how many days will take to get gForge account after registration?
Lloyd McKenzie (Aug 10 2017 at 05:13):
@Jayashree Surnar In theory one business day, but over the summer it can take longer. I've gone in and granted you approval. Look for a confirmation email in your inbox or spam box.
Jayashree Surnar (Aug 10 2017 at 05:15):
thank you @Lloyd McKenzie
Jayashree Surnar (Aug 10 2017 at 06:34):
(deleted)
Brian Reinhold (Aug 15 2017 at 14:57):
Okay, that seems rather intense. At the moment I am looking at the Forge use of the ImplementationGuide structure definition. Populating most of these elements seems reasonably straight forward until one gets to the pages. I assume that is the place where a great deal of human readable content goes. It is also very 'free-form'. As far as I can tell I can put whatever I want in these pages... oh clearly with the intent to help the reader of the pages to understand how to implement the profiles
The tricky part to this is the links between the pages and structure definition itself. I come up against the same problem as with the links to profiles. Sure I can create a profile, but where am I supposed to put them? At the moment I make up a URL that will do nothing but give a 404 error should one try and navigate to the link since I do not know what to do with that. But I need a legal URL to stop errors.
The same is true of these Implementation Guide pages. Do they end up going in the same place as the profiles?
Eric Haas (Aug 15 2017 at 15:51):
THe IG resource represents the artifacts that will populate the IG. (think of it as a glorified table of contents.) It doesn't create an IG without tooling. Lloyd makes it work through his magic and I think David has done something in clinFHIR too. I don't know if Furore does something similar as well.
Brian Reinhold (Aug 15 2017 at 15:54):
THe IG resource represents the artifacts that will populate the IG. (think of it as a glorified table of contents.) It doesn't create an IG without tooling. Lloyd makes it work through his magic and I think David has done something in clinFHIR too. I don't know if Furore does something similar as well.
Well Forge has an ImplementationGuide option but at the moment I am just creating *.md files for the 'page' element. I don't think is generates a document or a set of linked html files from it but I do have a set of xml profiles and am starting on a set of 'pages'.
Grahame Grieve (Aug 16 2017 at 02:20):
the IG resource doesn't have to list all or even any of the pages. The intent is that it can list key entry point pages (toc, version history etc) and tools can jump a user straight to them
Michel Rutten (Aug 16 2017 at 11:33):
@Grahame Grieve this comes as a bit of a surprise...? I always assumed the IG.pages element was intended to represent the full content structure with links to all pages. This is what we're currently planning to generate from the IG editor in our Simplifier platform.
Lloyd McKenzie (Aug 16 2017 at 13:35):
The IG publisher uses IG.pages to generate a table of contents fragment. Any pages that aren't listed there won't show up.
Michel Rutten (Aug 16 2017 at 13:42):
OK, that makes sense. So the IG.pages component should not be considered to represent a complete manifest of all the content in the IG. I'll keep that in mind.
Grahame Grieve (Aug 16 2017 at 13:47):
it can list everything. But it doesn't have to
Grahame Grieve (Aug 16 2017 at 13:48):
it sort of depends how you lay the content out.
Michel Rutten (Aug 16 2017 at 14:03):
Understood, thanks for the insight.
Martijn Harthoorn (Aug 16 2017 at 14:09):
I think in Simplifier we will have to require that the pages tree has the complete manifest. Otherwise, we have no way to specify what to put in an export (zip).
Martijn Harthoorn (Aug 16 2017 at 14:19):
Since ImplementationGuide.binary and ImplementationGuide.package also need to be exhaustive for that.
Eric Haas (Aug 16 2017 at 16:39):
I have been looking at the pages in IG resource and how is it different from a site map? Can I generate the site map from it or vice versa?
Lloyd McKenzie (Aug 16 2017 at 19:40):
The IGPublisher does generate a table of contents wish is essentially a site map (with section numbers)
Martijn Harthoorn (Aug 18 2017 at 08:21):
So, the IG resource is a manifest for all the 'regular' FHIR resources, it's a manifest for all the css, images and other binary content, but it's not a manifest for the pages? Or do you also store those in the binary content?
Lloyd McKenzie (Aug 18 2017 at 16:56):
It doesn't need to be a manifest for the binary content either. The only thing it must point to are the resources. If you point to all the pages, you'll get a table of contents. I haven't found a good reason to point to the binary content yet.
Eric Haas (Aug 18 2017 at 21:17):
So @Martijn Harthoorn and @David Hay , what do you want in the IG resource to make all the magic on your end happen? all the conformances resources, examples, pages, images?
David Hay (Aug 18 2017 at 21:36):
Well, to be honest I really haven't put a lot of thought into the next steps. The main goal I had was to be able to represent graphically all the resources in the IG, and for that I needed the resources. Links to pages & examples are a logical next step if the tooling was to extend to a more complete display... Is there a good example that we could experiment with?
Eric Haas (Aug 18 2017 at 22:03):
Mine are minimal. Lloyds are probably complete since that what drives all his preprocessing.
Eric Haas (Aug 18 2017 at 22:11):
@Lloyd McKenzie ?
Lloyd McKenzie (Aug 19 2017 at 00:19):
I need all of the pages and resources to be listed. I have no need for binaries and other artifacts
.
Eric Haas (Aug 19 2017 at 18:58):
Does is reflect the page heirarchy (like a visual sitemapping) or is it a flat list of pages?
Lloyd McKenzie (Aug 20 2017 at 02:42):
It reflects the hierarchy in which the pages are nested in the ImplementationGuide.
Eric Haas (Aug 20 2017 at 22:24):
is sdc a good example?
David Hay (Aug 21 2017 at 02:32):
That should do. I'll have a play :)
David Hay (Aug 21 2017 at 02:53):
btw - I assume that the zip download is the standard output from the IG tool? (in terms of folder structure in particular)...
Martijn Harthoorn (Aug 21 2017 at 13:44):
Our current status is that a Simplifier project can contain FHIR resources, images, page contents (.md, etc) and one or more IG resources. And in order to do a sensible export of an IG (zip) we need a manifest. Because otherwise we can only export the project as a whole. Thinking of a use case where we have an IG in more than one language or more than one target audience, not all content in the project is relevant for each IG.
Grahame Grieve (Aug 21 2017 at 13:45):
I'm not sure what you are saying...
Martijn Harthoorn (Aug 21 2017 at 13:50):
What is needed for an exporting an implementation guide (zip) is a subset of the files that are in a project. So for that we need some form of manifest (a complete description of all needed files to render the IG and/or to build a FHIR server). And until now I assumed that the IG-resource would serve that purpose.
Grahame Grieve (Aug 21 2017 at 13:51):
no one here has said that it can't, only that it doesn't have to
Martijn Harthoorn (Aug 21 2017 at 13:51):
That's good to hear :)
Grahame Grieve (Aug 21 2017 at 13:51):
however my experience is that there are 2 distinct purposes at play here - presenting a published IG, and publishing one.
Eric Haas (Aug 21 2017 at 14:13):
I think we are talking here about 'presenting a published IG' specifically using the IG resource. For 'publishing one' because you need more than the IG resource to do it as is evidence by the need for a configuration file and the ensuing discussion on this stream.
Jose Costa Teixeira (Aug 21 2017 at 16:49):
can't those "other things that are needed" also be stored as resources? (media)?
(sorry if it does not make sense)
Jose Costa Teixeira (Aug 21 2017 at 16:49):
(deleted)
Grahame Grieve (Aug 21 2017 at 19:30):
the could be. the question is whether they should be
Last updated: Apr 12 2022 at 19:14 UTC
