Skip to content

Migrating PKI Documentation

Jump to bottom
Endi S. Dewata edited this page Sep 14, 2023 · 17 revisions

Overview

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.

Migrating a Page from Old Wiki to New Wiki

Adding the New Page

  • 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.

Updating the Old Page

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

This page has been moved to <URL>.

  • Click Save page

Updating Old Links

  • Click What links here in the old page.

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

[<URL> <link description>]

Adding New Links

  • 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:

link:<page-ID>[<link description>]

  • 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.

Migrating a Page from New Wiki to Source Repository

  • Select a page in the new wiki to migrate.

  • Create a file with .adoc extension.

  • Copy the content into the file.

  • Fix the content/links/images if necessary.

  • Add links in existing pages to the new page if necessary.

  • Commit the changes into a local branch.

  • Push the branch into a personal PKI repository.

  • Verify that the page is rendered correctly.

  • Create a pull request.

  • Review the pull request.

  • Merge the pull request.

  • Get the URL of the new page.

  • Change the page in the new wiki into:

This page has been moved to <URL>.

  • Change all links to the page in the new wiki into the new URL.

Finding Links to Old Wiki

To find AsciiDoc pages that contain links to old wiki:

$ grep link: `find . -type f` | sed -n "s/\.\/\([^:]*\).*link:\([^\[]*\).*/\1:\2/p" | grep https://www.dogtagpki.org | sort | uniq

To find MediaWiki pages that contain links to old wiki:

$ grep '\[' `find . -name "*.mediawiki" -type f` | sed -n "s/\.\/\([^:]*\).*\[\([^ ]*\).*/\1:\2/p" | grep https://www.dogtagpki.org | sort | uniq

See Also

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
Clone this wiki locally