Authoring Long Form Supplements and White Papers
This article will cover the process for publication in html form of long-form supplements and white papers. There is still a need for IHE classic format for supplements and for white papers, these are more of a long-form. Meaning that they are one html page that is continuous from top to bottom. These long-form supplements and white papers may link out to other IHE or external content.
This article will cover where the IHE committee authors the content using "Markdown" and "GitHub". This is distinct from when the IHE committee authors the content using "Microsoft Word" and the "Google Drive". The use of Word and Google Drive is an alternative, just not one covered here. With Word and Google Drive, the content would be published in PDF form. That PDF form might be published using the www.ihe.net method or might use the profiles.ihe.net method.
Examples:
- ITI - Internet User Authorization (IUA) supplement
- ITI - HIE White Paper
Given a "Development committee" has an approved work item to develop a long-form supplement or white paper. Where "development Committee" might be a Domain Technical committee, Domain Planning committee, or Regional Deployment committee.
The overall approach is:
- development Committee development of content
- development Committee review of content
- development Committee approval of content
- Publications Committee preparing html output (of content, and navigation to the content)
- Publications Committee, Co-Chairs, and author reviewing staging of html output
- Publications Committee migrating html output to profiles.ihe.net
- Publications Committee and development Committee tagging the GitHub repositories
- Publications Committee announcement to general public
This article recommends the use of "Markdown" and a dedicated GitHub repository. Deviations from this are discouraged, but there is no mandate.
The use of GitHub is understood as potentially difficult for people new to GitHub. This factor is typical of anything new, but GitHub is recognized as explicitly difficult given some unusual workflows (e.g., "pull-request"). This article is not going to train you on use of GitHub, but this article will try to limit the use of GitHub to the most simple workflows, and will not require anything other than a browser to use. Some will choose to use more advanced methods and tools like TortoiseGit.
The use of Markdown is also understood as not as easy to use as a graphical application like Microsoft Word. The main reasons to have chosen Markdown are that (a) it limits the creativity of the authors, thus keeping the content focused on the message and allowing IHE to apply style consistently, and (b) is an open format that will not be tied to a specific editing or display tool.
If your authors are not able to become comfortable with Markdown and GitHub, then I would recommend you continue to use Microsoft Word and Google Drive with publication in PDF form. For long-form content, PDF is acceptable.
Recommend that a dedicated GitHub repository be created for the work-item. This becomes more important after Public Comment as we recommend the use of GitHub "Issue" management for public comments and the revisions made to address the public comments.
IHE manages all GitHub repositories within the IHE GitHub Organization. The authors and co-chairs will need GitHub accounts, and those GitHub accounts associated with the IHE committee member team and the domain team. Contact John.Moehrke@gmail.com or CCarr@rsna.org to be added to these teams.
Once on the IHE team, you will be able to create a GitHub repository. Please create your repository following the naming convention to help keep things clear
<domain>"."<project>
for example: ITI.IUA, ITI.MHD, RAD.IMR, and DEV.SDPi
Note that some projects were created before this pattern.
Creating a Repository (for example "ITI.FooBar")
- Start https://github.com/IHE.
- Locate the green button on the right side of the screen "New".
- Push the green button.
- Put your name into "Repository name" (e.g., "ITI.FooBar").
- Select Public. We will not be using any Private repositories as we are an open organization.
- Select "Add a README file". This is useful to track your progress and provide instructions to your reviewers.
- Do not Select "Add .gitignore". This is for advanced use, no problem if you want to use it, but it is not further covered here.
- Do not Select "Choose a license". This is for advanced use, no problem if you want to use it, but it is not further covered here. We think that IHE should use "CC-BY-4.0", which is not on the dropdown (comments to publications committee are welcome).
- Push green "Create repository" button.
The only special thing you will want to do with that GitHub repository that you create is to set it up to publish the content to GitHub "Pages". To do this:
- With the GitHub repository showing in the browser, select the "Settings". This is found on the horizontal row starting with "Code".
- Scroll down the page until you see "GitHub Pages".
- Change the button that says "None" to "master".
- You do not need to change anything else.
- Push the "Save" button.
- You will now notice a green box showing "Your site is published at https://ihe.github.io/....." This link is what you will use for committee reviews. It is not the final publication for the use outside of your committee reviews. The content found on this site will reflect the content in your GitHub repository (with a few minutes delay after checkin).
There are many resources on the internet to help you understand Markdown. For example Markdown Cheat Sheet, and Markdown-cheatsheet. There are some applications that can be used to give a What-You-See-Is-What-You-Get (similar to WORD). The recommendation is to just use Markdown in a text editor. It is not that unusual, it is similar to editing in a Wiki (only different).
Create a file in your GitHub repository for your content. This is going to be the place where you put all your text. Do not put a date into the filename, as GitHub will track all changes. So the filename should represent your work item. One alternative is to write your content into the README.MD file, but this often feels odd.
Editing of the content file can be done directly in the GitHub web site. This is often a good system as it doesn't require any special access or special tooling.
- Select the file in your GitHub repository.
- Select the pencil graphic found in the upper-right corner of the file display. This is found to the right of the "Raw | Blame" button.
- Make the changes you want to make (using Markdown).
- Save the changes, at the bottom of the screen is a "Commit changes" section.
- Short title for the change
- Additional detail is only needed when you need to include it (later we will have more specific use of this, but for initial content creation this is good enough to leave blank)
- Leave "Commit directly to the master branch." (Later we will use the other mode, but for initial content creation this is good enough.)
- Push the "Commit changes" green button.
There are three ways your committee can review the content:
- The committee can review the markdown in markdown form. Some will like this, some will not.
- The committee members can click on the markdown file, and GitHub will automatically render it in a visual form (like the html form). This method has the GitHub user interface around the content. Some users might find that distracting.
- The committee members can view on the https://ihe.github.io/.... page that was configured above with the "Pages" step. This will render the content in html form without GitHub user interface around it. This is closest to the ultimate form.
Often committee review is communicated to the author via t-con, email, messaging, or other. The committee may choose to use "Issues", but that is not covered in the initial content, we will cover that in an article on public comment resolution.
At some point the committee formally approves the content for publication. This is an important part of governance.
The Publications Committee is the gatekeeper to all publications. This is similar goal to what this committee does for PDF. The steps are different, so they are outlined here.
- Typical quality and copywrite reviews of the content in the committee's repository
- Anything that needs to be updated (version number, date, etc), or corrected, must be made within the committee's repository
- The content is converted from Markdown to HTML. This is done using the pandoc tool, and a IHE managed stylesheet. This is often written into a batch file that can be part of the managed content of the repository. For example in HIE-Whitepaper, there is a "gen-html.bat" file with the following
pandoc -r gfm --template=https://github.com/IHE/publications/wiki/ihe_template.html --metadata title="HIE-Whitepaper" --metadata path-prefix="../../" -w html -o index.html README.md - Copy the html output to the publications repo (checked in to the repository)
- index.html files likely need to be updated to point at the new content, or explain the change
- Note that any change to the committee content must be committed to the committee GitHub repository
- Publication Committee requests review by co-chairs and author of the rendering in the publications repository http://ihe.github.io/publications
- Any corrections to committee content must be made to the committee repository, and step #1 is started over
- Any corrections needed to the index.html or other must be checked into the publications repository
- After approval, the content is copied (using Filezilla copy to the profiles.ihe.net)
- Publications Committee request review by co-chairs and author of the https://profiles.ihe.net
- Any corrections needed are done to the appropriate repositories and process started as appropriate
- Once fully approved the GitHub repositories are "tagged" (see below)
- Public notice of the newly published content
GitHub includes a feature of "tagging" a specific revision. Both the publications repository and the committee specific repository should be tagged. This tag is used in the future when someone wants exactly what was authored. This tag also enables more clear tracking of changes between various milestones. A tag is simply a title and description on a GitHub revision. The title and the description should be as clear as possible.
- A tag is added on a repository on the right side, under "About" is a section on "Releases". select the "Releases" text to open up the Releases page.
- "Draft a new release".
- Version should be simple and mostly numeric. Committee approved tag would tend to be the expected version with "-beta" suffix to indicate this is what the committee has approved. Formal releases would not have a suffix.
- The title should be simple, and may just indicate the milestone and version.
- The description should include a generalization of the changes from the previous tag. Often the description on a committee repository will be more expressive of the changes made, where the description on the publications repository may just indicate the domains that have content changes in that revision.
- Check the "This is a pre-release" for committee tags, do not check this for formal releases.
This article only covers the process from work-item approved to start, till Public Comment. The process for Public Comment to Publication is covered in another article.