How to create a documentation for an IPTC standard

Introduction

Creating a documention for an IPTC standard comprises these deliverables

  • documents about the development of the standard
  • the approved specification of the standard
  • documents supporting the use of the standard like a User Guide, or an Implementation Guideline

As this is user-friendly all these documents should be accessible by a shared home page and by specific URLs of the document-specific front pages.

These requirements can be met by Jekyll and this theme

  • a standard has to have its own Github repository
  • by that it would also have a Github Pages site at this URL https://iptc.github.io/{repository name}
  • A home page at this URL can provide an overview with links to the different documents, labeled as “book” on this test site.
  • Navigation sidebars: the overall page(s) and each book can have its specific navigation sidebar. The navigation at the top provides a link at its left end to return to the overall home page from any book.

Managing the page documents

Jekyll and this document supports page document file in HTML and in Markdown format. Even a mix in a single file is possible.

The page files can be arranged in different subfolders of the top level pages folder; this way a subfolder can hold the overview pages, and other subfolders all the pages for a book. Despite of this folder structure all page names are following the base URL of the site (https://iptc.github.io/{repository name}, see above) and not reflected by URL parts for the folder: a page book1_chapter1.html in the subfolder for book 1 would result in the page URL https://iptc.github.io/{repository name}/book1_chapter1.html

Tags: formatting