Child pages
  • Document Review
Skip to end of metadata
Go to start of metadata

This page defines the goals, process, and current release plan for review of OPNFV documentation.

 

This section describes the documents that are planned to be developed and reviewed in the current release. The goal is to use the table below to organize the review process, e.g. timing, resources, results capturing, etc. Results capturing, e.g. thru JIRA issues, is a key goal so we know that the reviews/tests were adequately completed and we have a record of the results, to help improve the process going forward.

 

ProjectDocuments PlannedReviewers/TestersStatus/Notes
Copper

Copper Project

User Guide

Install Guide

Release Notes

Bryan

Bryan

Bryan

Bryan

Complete, in review

Complete, in review

Complete, in review

Complete, in review

Doctor   
Domino   
Escalator   
HA   
Ipv6   
Models   
Movie   
Multisite   
KVM for NFV   
ONOSFW   
Open vSwitch for NFV   
OVNO   
Parser   
PolicyTest   
Prediction   
Promise   
Resource Scheduler   
SDNVPN   
Service Function Chaining (SFC)   

Goals

OPNFV documentation is key to the public perception of OPNFV. Having an effective documentation program requires us to consider these goals:

  • All documentation should be available for review early enough in the release process to allow a quality review process.
  • Documents should be tested, meaning assessed per technical correctness, clarity/usability, and presentation quality/consistency.
  • OPNFV should strive for continuous improvement of its documentation program, and consistency with best practices for documentation in major open source projects.

Process

The following table outline the process and considerations for documentation review.

StepDescriptionConsiderations
Project docs ready for reviewPer the current release plan, project documentation should be in place for pre-release verification by MS2 (Feature Code Freeze).We may need a little more time for developers to finish the critical-path work, so they can then develop/align docs with the work so far. MS3 (Installation Ready) or MS4 (Test Code Freeze) may be better goals. Other projects that don't have installation or code goals (e.g. analysis/requirements/blueprints focused projects) should have the same deadline.
Technical testingVerify doc content is correct, e.g. accurately reflects the project's results (what was done, analyzed, etc) and processes for install/use of features (as applicable).

The testers will need familiarity and skills to technically assess the docs, but if possible also need to be someone other than the team that developed the project's results. It's recommended to have a project member assigned to "play the role" of an end-user for example, testing install/use guides for correctness.

OPNFV should also test its docs again during the support period for a release, to ensure that the docs have not been broken in the process (e.g. install/use information is out of date or just doesn't work anymore).

Clarity/Usability testing

Verify docs effectively support end-user needs, e.g. the content is adequate and understandable by someone with a reasonable level of technical awareness of the subject.

It's even more important for this that the tester be someone other than the documentation developer. Having testers with multiple skill levels be even better, e.g. someone pretty familiar with the subject, and someone less familiar but with experience as a user of technical documentation.
Presentation Quality / Consistency testingVerify docs have a consistent look and feel per OPNFV style guides, and meet a reasonable level of publication-readiness given that the authors are not professional writers/editors/publishers.OPNFV needs to develop and evolve a high-quality style guide which is supported by the doc toolchain in use. Professional services may be needed to provide an objective and skilled assessment of publication-readiness (at least once per release), if OPNFV does not have members with the needed skillsets/experience.
  • No labels