Announcing the PKP Documentation Hub

By Mike Nason

At the PKP Code Sprint in 2017, a group of PKP community members/supporters created a report on PKP’s myriad documentation. As our software had grown over ~20 years, so too had our solutions for platform- and task-specific documentation. By the end of the sprint, the group identified redundant and deprecated documentation for outdated versions of software, specific plugins, unique tasks, and information on publishing. Documents existed in various corners of our website: on the PKP Wiki, as commonly shared forum posts, in Github, and in the service known as Gitbook. Not only was documentation hard to locate, but it was also difficult for community members to contribute. It was clear that we had a lot of work ahead of us.

Using the information accumulated by the members of the sprint group as a starting point, PKP has taken the year to narrow down our existing documentation and weed unneeded materials. The result is the creation of a new home for the documentation our users need most. Introducing version 1.0 of the PKP Documentation Hub.

The PKP Documentation Hub utilizes a standalone static website generated via Jekyll from a singular Github repository. Our documentation lives in one place and is as easy to contribute to like any of PKP’s other projects. Jekyll provides us with more control over display and organization than our prior documentation solutions while also being more lightweight and agile than a full-fledged CMS. Some of the documentation available at launch includes:

Over the next year we’ll be improving the hub with:

  • new documentation (including improved developer documentation)
  • updates to older documentation (including the technical reference, and Learning OMP)
  • new features
  • guidelines and policies for contributing

But what about the old documentation?

All primary documentation has been moved into the new hub, and we will keep legacy documents available there indefinitely (for example, the OJS 2 technical guide, and Learning OJS 2). The old documentation locations either have already been disabled or will be in the following timeline:

  • all materials hosted on Gitbook are unavailable effective immediately;
  • all materials hosted outside of the documentation hub repository on Github have been cleared out and redirect to the hub. These repo locations will remain for six months to ensure that any contributors who may have been working on forked documentation have time redirect their commits;
  • the PKP wiki will be taken down after ~1 year, effective September 1st, 2019.

If you have been translating a forked version of a document or have any questions or suggestions about documentation, please contact documentation@publicknowledgeproject.org for assistance.

Facebook
Twitter
LinkedIn