Last week I published an edit of the APNIC Internet Number Resource Policies manual. This was the final phase of a drawn out process to consolidate and merge all of the previous APNIC resource policy documentation into a single, easy-to-use document.
Previously, APNIC’s resource related policies were contained in seven separate policies, causing an unnecessary administrative burden on the Policy Development Process and making it more difficult for stakeholders to access and identify all the policies relevant to their particular interest.
The idea of documentation reform was first raised at APNIC 34 in Phnom Penh, Cambodia. At the time, I argued that the format and archival procedures for official APNIC documents was cumbersome and out-dated and the community gave its support for a review and possible format change from plain text to something more web-friendly, such as XML format. The community also agreed to move toward a single document architecture.
Finding a format
After some investigations and further consideration, the decision was made to keep plain text as the official format as other formats didn’t provide enough advantage; especially if we moved to a single document policy manual.
In other words, maintaining seven individual policy documents in plain text and html was cumbersome, but maintaining a single policy manual according to established procedures, was efficient enough. The benefit of keeping the historical archive intact, in a single format, outweighed the advantages of moving to XML. I discussed this at APNIC 35:
The Secretariat has since adopted an internal Document Management System. Maintenance of policy documentation was considered in the evaluation phase of selection process for the new system. However, again, the benefit of maintaining the historical archiving procedures outweighed the advantage of migrating to an automated system.
The document management system is used to store the policy archive files, but the archive does not rely on the systems version control. Version control is maintained in the header portion of the document as it always has been. As the document management system is not normally publicly accessible, the archive is simply mirrored to the APNIC FTP server for public access.
Bringing it all together
So while the archival procedures and file format of the documents have not changed in any material way, the content has undergone a significant evolution.
After several drafts, re-drafts, internal reviews, external reviews, and a number of community consultations, the final draft was published for comment during the APNIC 39 conference in Fukuoka, Japan.
Although earlier drafts had been posted for community review and feedback, this was the first version published under the official APNIC Document Editorial policy; and following the one-month comment period it became the official APNIC Internet Number Resource Policies manual.
However, that initial version still contained a certain amount of unedited text, which was preserved to make it easier to track the evolution from the previous documents to the new single document.
As the separate policies were maintained differently for many years, even areas that were originally intended to be uniform had evolved so that there was a level of near, but not exact, duplication resulting in some inconsistencies in phrasing. Publishing version one with these incompatibilities allowed a better understanding of evolution of the document rather than introduce wholesale change at the same time as merging the documents.
At APNIC 40 in Jakarta, Indonesia I presented the final version to the community, highlighting how I proposed to resolve the most contentious of these inconsistencies. That document is the draft of the version published as the official policy on 10 November 2015.
Change is best when properly understood
In publishing this latest version I have also implemented another key change to the policy documentation; the introduction of a change log. This will provide a much better understanding of how and why policy changes over time. It is an incremental improvement to the APNIC Official Document archival process. Please provide any feedback on this new feature to policy@apnic.net.
The next project to improve the usability of the APNIC policy archive is to create a retrospective change log of previous policy document changes for IPv4, IPv6, and AS numbers. This change log will not only serve as an historical record, but also provide an easy reference tool for the interpretation of current policy analysis.
I will report on this new project at APNIC 41 in Auckland, New Zealand. Once these three main policies are logged, a decision will be made about whether there is sufficient benefit to warrant extending the project scope to include other archival policy documents.
The views expressed by the authors of this blog are their own and do not necessarily reflect the views of APNIC. Please note a Code of Conduct applies to this blog.