Currently most of the upstream PKI docs are residing at https://www.dogtagpki.org (a.k.a. the old wiki) which has some issues:

• The infrastructure must be maintained manually (e.g. backup, upgrade).

• The pages are written in MediaWiki format. The preferred format now is AsciiDoc.

• The pages are not versioned to match the code (e.g. there is only one CLI page for all PKI versions) unless the page is manually split into separate versions (e.g. separate pages for PKI 10.5 CLI and PKI 10.6 CLI).

GitHub provides a wiki space at https://github.com/dogtagpki/pki/wiki (a.k.a. the new wiki) which addresses some of the issues:

• The infrastructure is maintained by GitHub.

• GitHub wiki supports multiple formats including AsciiDoc, Markdown, and MediaWiki (although not completely identical to the old wiki)

However, the pages are still not versioned to match the code. To address the last issue the pages should eventually be moved into the source repository at https://github.com/dogtagpki/pki/tree/master/docs. This way when the code is branched, the docs will be branched as well. In addition to that, ideally pages that are added into the source repository should be considered a product documentation instead of wiki, so it should meet some standards:

• The content should be more formal. For example, don’t use "I". Avoid using "you" if possible.

• The document should be in AsciiDoc format.

• The document should be nicely formatted (e.g. don’t use bullet points excessively).

• The document should be consistent (e.g. use $ for all command prompts).

• The document should be organized into:

  • Installation Guide: for people who install the packages and create the server instances. This guide also includes post-installation configurations that require direct updates to the configuration files on the operating system.

  • Administration Guide: for people who have full access to the server machine and configuration.

  • User Guide: for people who are only allowed to access the server via the web interface (no direct access to the machine) including agents, auditors, and end-entities.

  • Programming Guide: for people who write code using PKI web services or PKI programming API.

  • Development Guide: for people who develop PKI.

This page describes the two-step process to migrate pages from the old wiki to the new wiki and eventually into the source repository. It’s possible to migrate directly from the old wiki into the source repository in a single step, but the two-step process might be easier if it is to be done as a low-priority background task.

• Select a page in the old wiki to migrate.

• Click edit at the bottom of the page.

• Click New Page in the new wiki.

• Enter a title for the new page. It doesn’t have to be the same as the old page. Simplify the title if possible.

• Copy and paste the content of the old page into the new page. Change the Edit mode to MediaWiki. Note that although GitHub wiki supports MediaWiki format, some things may be rendered differently.

• Optionally, convert the content into AsciiDoc, and change the Edit mode to AsciiDoc. The conversion can be done manually or with tools such as Pandoc.

• Fix the links/images if necessary.

• Click Preview to verify that the content is correctly rendered. Compare with the old page.

• Click Save Page.

• Copy the URL of the new page. Change the old page into:

• Click Save page

• Click What links here in the old page.

• Replace all links to the old page in the old wiki with the following:

• Find an existing page in the new wiki to link to the new page such that the new page can be found from the new wiki front page.

• Edit that page and add a link to the new page. See other links in that page as an example. In AsciiDoc format the link will look like this:

• The <page-ID> should be just the last part of the URL of the new page. Don’t put the whole URL in the link.

• Click Save Page then click the link to verify it.