docs/documentation.rst

   1 .. _documentation-guide:
   2
   3 ###################
   4 Documentation Guide
   5 ###################
   6
   7 This guide provides details on how to contribute to the OpenDaylight
   8 documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
   9 reStructuredText_ for documentation, although the `Documentation
  10 Group`_ is generally trying to move toward using reStructuredText_ and
  11 Sphinx_ to build it as it is widely-used to provide both HTML and pdf
  12 documentation that can be easily versioned alongside the code. It also
  13 offers similar syntax to Markdown which is familiar to large numbers of
  14 people.
  15
  16 .. contents:: Contents
  17    :depth: 2
  18    :local:
  19
  20 Style Guide
  21 ===========
  22
  23 This section serves two purposes:
  24
  25 #. A guide for those writing documentation to follow.
  26 #. A guide for those reviewing documentation.
  27
  28 That being said, assuming that the content is usable, the bias should
  29 be toward merging it rather than blocking on relatively minor edits.
  30
  31 Formatting Preferences
  32 ----------------------
  33
  34 In general, the documentation team has focused on trying to make sure
  35 that the instructions are comprehensible, but not being overly pedantic
  36 about these things. Along those lines, while we would prefer the
  37 following, generally they aren't a reason to -1 in and of themselves:
  38
  39 * No trailing whitespace
  40 * Line wrapping at something reasonable, i.e., 72–100 characters
  41
  42 Key terms
  43 ---------
  44
  45 * Functionality: something useful a project provides abstractly
  46 * Feature: a Karaf feature that somebody could install
  47 * Project: a project within OpenDaylight, projects ship features to
  48   provide functionality
  49 * OpenDaylight: this refers to the software we release, use this in
  50   place of OpenDaylight controller, the OpenDaylight controller, not
  51   ODL, not ODC
  52
  53   * Since there is a controller project within OpenDaylight, using
  54     other terms is hard.
  55
  56 Common writing style mistakes
  57 -----------------------------
  58
  59 * In per-project user documentation, you should never say *git clone*,
  60   but should assume people have downloaded and installed the controller
  61   per the getting started guide and start with ``feautre:install
  62   <something>``
  63 * Avoid statements which are true about part of OpenDaylight, but not
  64   generally true.
  65
  66   * For example: "OpenDaylight is a NETCONF controller." It is, but
  67     that is not all it is.
  68
  69 * In general, developer documentation should target external developers
  70   to your project so should talk about what APIs you have and how they
  71   could use them. It *should not* document how to contribute to your
  72   project.
  73
  74 Grammar Preferences
  75 ^^^^^^^^^^^^^^^^^^^
  76
  77 * Avoid contractions: use cannot instead of can't, it is instead of
  78   it's, and the like.
  79
  80 Things to get right with spacing and capitalization
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 *Note that all of these apply when using them in text. If they are used
  84 as part of URL, class name, or something similar, use the actual
  85 capitalization and spacing.*
  86
  87 * ACL: not Acl or acl
  88 * API: not api
  89 * ARP: not Arp or arp
  90 * datastore: not data store, Data Store, or DataStore (unless it's a
  91   class/object name)
  92 * IPsec, not IPSEC or ipsec
  93 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
  94 * Karaf: not karaf
  95 * Linux: not LINUX or linux
  96 * NETCONF: not Netconf or netconf
  97 * Neutron: not neutron
  98 * OSGi: not osgi or OSGI
  99 * Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch, etc.
 100 * OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight, etc.
 101
 102   * also avoid abbreviations like ODL and ODC
 103
 104 * OpenFlow: not Openflow, Open Flow, openflow, etc.
 105 * OpenStack: not Open Stack or Openstack
 106 * QoS: not Qos, QOS, or qos
 107 * RESTCONF: not Restconf or restconf
 108 * RPC not Rpc or rpc
 109 * URL not Url or url
 110 * VM: not Vm or vm
 111 * YANG: not Yang or yang
 112
 113 reStructuredText-based Documentation
 114 ====================================
 115
 116 When using reStructuredText, we try to follow the python documentation
 117 style guide. See: https://docs.python.org/devguide/documenting.html
 118
 119 The best reference for reStrucutedText syntax seems to be the Sphinx
 120 Primer on reStructuredText_.
 121
 122 To build and review the reStructuredText documentation locally you must
 123 have installed locally:
 124
 125 * python
 126 * python-tox
 127
 128 Which both should be available in most distribution's package managers.
 129
 130 Then simply run tox and open the html produced via your favorite web
 131 browser as follows:
 132
 133 .. code-block:: bash
 134
 135    git clone https://git.opendaylight.org/gerrit/docs
 136    cd docs
 137    git submodule update --init
 138    tox -edocs
 139    firefox docs/_build/html/index.html
 140
 141 .. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
 142           sure you run tox -edocs`_
 143
 144 Directory Structure
 145 -------------------
 146
 147 The directory structure for the reStructuredText documentation is
 148 rooted in the ``docs`` directory inside the ``docs`` ``git``
 149 repository.
 150
 151 Below that there are guides hosted directly in the ``docs`` ``git``
 152 repository and there are guides hosted in remote ``git`` repositories.
 153 Usually those are for project-specific information.
 154
 155 For example here is the directory layout on June, 28th 2016::
 156
 157    $ tree -L 2
 158    .
 159    ├── Makefile
 160    ├── conf.py
 161    ├── documentation.rst
 162    ├── getting-started-guide
 163    │   ├── api.rst
 164    │   ├── concepts_and_tools.rst
 165    │   ├── experimental_features.rst
 166    │   ├── index.rst
 167    │   ├── installing_opendaylight.rst
 168    │   ├── introduction.rst
 169    │   ├── karaf_features.rst
 170    │   ├── other_features.rst
 171    │   ├── overview.rst
 172    │   └── who_should_use.rst
 173    ├── index.rst
 174    ├── make.bat
 175    ├── opendaylight-with-openstack
 176    │   ├── images
 177    │   ├── index.rst
 178    │   ├── openstack-with-gbp.rst
 179    │   ├── openstack-with-ovsdb.rst
 180    │   └── openstack-with-vtn.rst
 181    └── submodules
 182        └── releng
 183            └── builder
 184
 185 The ``getting-started-guide`` and ``opendaylight-with-openstack``
 186 directories correspond to two guides hosted in the ``docs`` repository,
 187 while the ``submodules/releng/builder`` directory houses documentation
 188 for the `RelEng/Builder`_ project.
 189
 190 Inside each guide there is usually an ``index.rst`` file which then
 191 includes other files using a ``toctree`` directive. For example::
 192
 193    .. toctree::
 194       :maxdepth: 1
 195
 196       getting-started-guide/index
 197       opendaylight-with-openstack/index
 198       submodules/releng/builder/docs/index
 199
 200 This creates a table of contents on that page where each heading of the
 201 table of contents is the root of the files that are included.
 202
 203 .. note:: When including rst files using ``toctree`` omit the .rst at
 204           the end of the file name.
 205
 206 Documentation Layout and Style
 207 ------------------------------
 208
 209 As mentioned previously we try to follow the python documentation style
 210 guide which defines a few types of sections::
 211
 212     # with overline, for parts
 213     * with overline, for chapters
 214     =, for sections
 215     -, for subsections
 216     ^, for subsubsections
 217     ", for paragraphs
 218
 219 We try to follow the following structure based on that recommendation::
 220
 221     docs/index.rst                 -> entry point
 222     docs/____-guide/index.rst      -> part
 223     docs/____-guide/<chapter>.rst  -> chapter
 224
 225 In the ____-guide/index.rst we use the # with overline at the very top
 226 of the file to determine that it is a part and then within each chapter
 227 file we start the document with a section using * with overline to
 228 denote that it's the chapter heading and then everything in the rest of
 229 the chapter should use::
 230
 231     =, for sections
 232     -, for subsections
 233     ^, for subsubsections
 234     ", for paragraphs
 235
 236 Troubleshooting
 237 ---------------
 238
 239 Nested formatting doesn't work
 240 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 241
 242 As stated in the reStructuredText_ guide, inline markup for bold,
 243 italic, and fixed-width can't be nested. Further, it can't be mixed
 244 with hyperlinks, so you can't have bold text link somewhere.
 245
 246 This is tracked in a `Docutils FAQ question
 247 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`,
 248 but there is no clear current plan to fix this.
 249
 250 Make sure you've cloned submodules
 251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 252
 253 If you see an error like this::
 254
 255    ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
 256    Resource file '*.robot' does not exist.
 257
 258 It means that you haven't pulled down the git submodule for the
 259 integration/test project. The fastest way to do that is::
 260
 261    git submodule update --init
 262
 263 In some cases, you might wind up with submodules which are somehow
 264 out-of-sync and in that case, the easiest way to fix it is delete the
 265 submodules directory and then re-clone the submodules::
 266
 267    rm -rf docs/submodules/
 268    git submodule update --init
 269
 270 .. warning:: This will delete any local changes or information you made
 271              in the submodules. This should only be the case if you
 272              manually edited files in that directory.
 273
 274 Make sure you run tox -edocs
 275 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 276
 277 If you see an error like::
 278
 279    ERROR:   docs: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs/log/docs-1.log)', 1)
 280    ERROR:   docs-linkcheck: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs-linkcheck/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs-linkcheck/log/docs-linkcheck-1.log)', 1)
 281
 282 It usually means you ran `tox` and not `tox -edocs`, which will result
 283 in running jobs inside submodules which aren't supported by the
 284 environment defined by the `requirements.txt` file in the documentation
 285 tox setup. Just run tox -edocs and it should be fine.
 286
 287 Clear your tox directory and try again
 288 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 289
 290 Sometimes, tox will not detect when your ``requirements.txt`` file has
 291 changed and so will try to run things without the correct dependencies.
 292 This usually manifests as ``No module named X`` errors or
 293 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
 294 directory and building again::
 295
 296    rm -rf .tox
 297    tox -edocs
 298
 299 Builds on Read the Docs
 300 ^^^^^^^^^^^^^^^^^^^^^^^
 301
 302 It appears as though the Read the Docs builds don't automatically clear
 303 the file structure between builds and clones. The result is that you
 304 may have to clean up the state of old runs of the build script.
 305
 306 As an example, this patch:
 307 https://git.opendaylight.org/gerrit/41679
 308
 309 Finally fixed the fact that our builds for failing because they were
 310 taking too long by removing directories of generated javadoc that were
 311 present from previous runs.
 312
 313 AsciiDoc-based Documentation
 314 ============================
 315
 316 Information on the AsciiDoc tools and build system can be found here:
 317 https://wiki.opendaylight.org/view/Documentation/Tools
 318
 319 Directory Structure
 320 -------------------
 321
 322 The AsciiDoc documentation is all located in the ``manuals`` directory
 323 of the ``docs`` ``git`` repository. An example of the directory
 324 structure on June 28th, 2016 can be seen here::
 325
 326    $ tree -L 4
 327    .
 328    ├── common
 329    │   └── app_support.xml
 330    ├── developer-guide
 331    │   ├── pom.xml
 332    │   └── src
 333    │       └── main
 334    │           ├── asciidoc
 335    │           └── resources
 336    ├── getting-started-guide
 337    │   ├── pom.xml
 338    │   └── src
 339    │       └── main
 340    │           ├── asciidoc
 341    │           └── resources
 342    ├── howto-openstack
 343    │   ├── pom.xml
 344    │   └── src
 345    │       └── main
 346    │           ├── asciidoc
 347    │           └── resources
 348    ├── pom.xml
 349    ├── readme
 350    │   ├── pom.xml
 351    │   └── src
 352    │       └── main
 353    │           └── asciidoc
 354    └── user-guide
 355        ├── pom.xml
 356        └── src
 357            └── main
 358                ├── asciidoc
 359                └── resources
 360
 361 Each of the top-level directories under ``manuals`` is a whole guide by
 362 itself and it contains a ``pom.xml`` file saying how to build it, a
 363 ``src/main/asciidoc`` directory with AsciiDoc source files and a
 364 ``src/main/resources`` directory containing images.
 365
 366 Troubleshooting
 367 ---------------
 368
 369 See `AsciiDoc Tips`_ on the wiki for more information.
 370
 371 Common AsciiDoc mistakes
 372 ^^^^^^^^^^^^^^^^^^^^^^^^
 373
 374 See also `AsciiDoc Tips`_.
 375
 376 * Lists that get formatted incorrectly because of no blank line above
 377   the list.
 378 * Numbered lists that are formatted incorrectly and every bullet winds
 379   up being 1
 380
 381 Migration from AsciiDoc to ReStructuredText
 382 ===========================================
 383
 384 Automatically
 385 -------------
 386
 387 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
 388 produce DocBook as part of our build chain from AsciiDoctor. In
 389 practice, for modest-sized migrations doing things by hand works fairly
 390 well.
 391
 392 By Hand
 393 -------
 394
 395 Converting from AsciiDoc to reStructuredText is usually pretty
 396 straightforward and involves looking up the basic syntax for what you
 397 want to do by looking it up in the reStructuredText_ guide.
 398
 399 The differences are usually minor and fast to change.
 400
 401 Also, because of how fast Sphinx builds, and how fast it is to refresh
 402 the HTML documentation rapid iteration is very easy.
 403
 404 Bold/Italics/Verbatim Formatting
 405 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 406
 407 This is mostly minor syntax issues. In AsciiDoc you do inline
 408 formatting something like this::
 409
 410    *bold* _italic_ +verbatim+ `verbatim`
 411
 412 In reStructuredText, things are slightly different::
 413
 414    **bold** *italic* ``verbatim``
 415
 416 Images
 417 ^^^^^^
 418
 419 Image formats change from something like::
 420
 421    .OpenStack Architecture
 422    image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
 423
 424 To something like::
 425
 426    .. figure:: images/dlux-default.png
 427
 428 A helpful regular expression for automating the replacements is
 429 something like::
 430
 431    search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
 432    replace: $1.. figure:: images/dlux/$3\n$1   :width: $5\n\n$1   $2
 433
 434
 435 Project Documentation Requirements
 436 ==================================
 437
 438 Submitting Documentation Outlines (M3)
 439 --------------------------------------
 440
 441 #. Determine the features your project will have and which ones will be
 442    ''user-facing''.
 443
 444    * In general, a feature is user-facing if it creates functionality that a
 445      user would direction interact with.
 446    * For example, ``odl-openflowplugin-flow-services-ui`` is likely
 447      user-facing since it installs user-facing OpenFlow features, while
 448      ``odl-openflowplugin-flow-services`` is not because it provides only
 449      developer-facing features.
 450
 451 #. Determine pieces of documentation you need provide based on the features
 452    your project will have and which ones will be user-facing.
 453
 454    * The kinds of required documentation can be found below in the
 455      :ref:`requirements-for-projects` section.
 456    * Note that you might need to create multiple different documents for the
 457      same kind of documentation. For example, the controller project will
 458      likely want to have a developer section for the config subsystem as well
 459      as a for the MD-SAL.
 460
 461 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
 462 #. For each piece of documentation find the corresponding template in the docs repo.
 463
 464    * For user documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_user_guide.adoc``
 465    * For developer documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_developer_guide.adoc``
 466    * For installation documentation (if any): ``docs.git/manuals/readme/src/main/asciidoc/template_installation_guide.adoc``
 467
 468 #. Copy the template into the appropriate directory for your project.
 469
 470    * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/${project-shortname}/${feature-name}-user.adoc``
 471    * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/${project-shortname}/${feature-name}-dev.adoc``
 472    * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/${project-shortname}/${feature-name}-install.adoc``
 473
 474 #. Edit the template to fill in the outline of what you will provide using the
 475    suggestions in the template.
 476
 477    * DO NOT leave any sections blank as blank sections will cause build errors.
 478
 479 #. Link the template into the appropriate core adoc file
 480
 481    * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/bk-user-guide.adoc``
 482    * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/bk-developers-guide.adoc``
 483    * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/bk-install-guide.adoc``
 484    * Add a line like:
 485
 486      .. code-block:: none
 487
 488         include::${project-shortname}/${feature-name}-user.adoc[]
 489
 490    * Make sure there is a blank line between your include statement and any others as this prevents sections from running into each other.
 491
 492 #. Make sure the documentation project still builds.
 493
 494    * Run ``mvn clean install`` from the root of the cloned docs repo.
 495
 496      * After that, you should be able to find the PDF and HTML version of the
 497        docs. Use ``find . -name *.pdf`` to find the PDF and the HTML is
 498        always at ``target/docbkx/webhelp/${manual-name}/index.html``.
 499
 500    * The `AsciiDoc tips <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_
 501      page provide common errors and solutions.
 502    * If you still have problems e-mail the documentation group at
 503      documentation@lists.opendaylight.org
 504
 505 #. Commit and submit the patch
 506
 507    #. Commit using:
 508
 509       .. code-block:: bash
 510
 511          git add --all && git commit -sm "Documentation outline for ${project-shortname}"
 512
 513    #. Submit using:
 514
 515       .. code-block:: bash
 516
 517          git review
 518
 519       See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
 520       page if you don't have git-review installed.
 521
 522 #. Wait for the patch to be merged or to get feedback
 523
 524    * If you get feedback, make the requested changes and resubmit the patch.
 525    * When you resubmit the patch, it's helpful if you also post a +0 reply to
 526      the gerrit saying what patch set you just submitted and what you fixed in
 527      the patch set.
 528    * The documentation team will also be creating (or asking projects to
 529      create) small groups of 2-4 projects that will peer review each other's
 530      documentation. Patches which have seen a few cycles of peer review will be
 531      prioritized for review and merge by the documentation team.
 532
 533 Expected Output From Documentation Project
 534 ------------------------------------------
 535
 536 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
 537
 538 * User/Operator Guide
 539 * Developer Guide
 540 * Installation Guide
 541
 542 These guides will consist of "front matter" produced by the documentation group
 543 and the per-project/per-feature documentation provided by the projects. Note
 544 that this is intended to be who is responsible for the documentation and should
 545 not be interpreted as preventing people not normally in the documentation group
 546 from helping with "front matter" nor preventing people from the documentation
 547 group from helping with per-project/per-feature documentation.
 548
 549 Boron Project Documentation Requirements
 550 ----------------------------------------
 551
 552 .. _kinds-of-docs:
 553
 554 Kinds of Documentation
 555 ^^^^^^^^^^^^^^^^^^^^^^
 556
 557 These are the expected kinds of documentation and target audiences for each kind.
 558
 559 * **User/Operator:** for people looking to use the feature w/o writing code
 560
 561   * Should include an overview of the project/feature
 562   * Should include description of availbe configuration options and what they do
 563
 564 * **Developer:** for people looking to use the feature in code w/o modifying it
 565
 566   * Should include API documentation, e.g., enunciate for REST, Javadoc for
 567     Java, ??? for RESTCONF/models
 568
 569 * **Contributor:** for people looking to extend or modify the feature's source
 570   code
 571
 572   .. note:
 573
 574      should be documented on the wiki not in asciidoc
 575
 576 * **Installation:** for people looking for instructions to install the feature
 577   after they have downloaded the ODL release
 578
 579   .. note:
 580
 581      audience is the same as User/Operator docs
 582
 583   * For most projects, this will be just a list of top-level features and
 584     options
 585
 586     * As an example, l2switch-switch as the top-level feature with the -rest
 587       and -ui options
 588     * We'd also like them to note if the options should be checkboxes (i.e.,
 589       they can each be turned on/off independently) or a drop down (i.e., at
 590       most one can be selected)
 591     * What other top-level features in the release are incompatible with each
 592       feature
 593     * This will likely be presented as a table in the documentation and the
 594       data will likely also be consumed by automated installers/configurators/downloaders
 595
 596   * For some projects, there is extra installation instructions (for external
 597     components) and/or configuration
 598
 599     * In that case, there will be a (sub)section in the documentation
 600       describing this process.
 601
 602 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
 603   documentation
 604
 605   * Generally, these should be done as a (sub)section of either user/operator
 606     or developer documentation.
 607   * If they are especially long or complex, they may belong on their own
 608
 609 * **Release Notes:**
 610
 611   * Release notes are required as part of each project's release review. They
 612     must also be translated into AsciiDoc for inclusion in the formal
 613     documentation.
 614
 615 .. _requirements-for-projects:
 616
 617 Requirements for projects
 618 ^^^^^^^^^^^^^^^^^^^^^^^^^
 619
 620 Projects MUST do the following
 621
 622 * Provide `AsciiDoc-format <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_ documentation including
 623
 624   * Developer documentation for every feature
 625
 626     * Most projects will want to logically nest the documentation for
 627       individual features under a single project-wide chapter or section
 628     * This can be provided as a single .adoc file or multiple .adoc files if
 629       the features fall into different groups
 630     * This should start with ~300 word overview of the project and include
 631       references to any automatically-generated API documentation as well as
 632       more general developer information (see
 633       :ref:`kinds-of-docs`).
 634
 635   * User/Operator documentation for every every user-facing feature (if any)
 636
 637     * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
 638     * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
 639     * This can be provided as a single .adoc file or multiple .adoc files if the features fall into different groups
 640
 641   * Installation documentation
 642
 643     * Most projects will simply provide a list of user-facing features and
 644       options. See :ref:`kinds-of-docs` above.
 645
 646   * Release Notes (both on the wiki and AsciiDoc) as part of the release review.
 647
 648 * This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
 649
 650   * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
 651   * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
 652
 653 * Projects MUST cooperate with the documentation group on edits and enhancements to documentation
 654
 655   * Note that the documentation team will also be creating (or asking projects to create) small groups of 2-4 projects that will peer review each other's documentation. Patches which have seen a few cycles of peer review will be prioritized for review and merge by the documentation team.
 656
 657 Timeline for Deliverables from Projects
 658 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 659
 660 * **M3:** Documentation Started
 661
 662   * Identified the kinds of documentation that will be provided and for what
 663     features
 664
 665     * Release Notes are not required until release reviews at **RC2**
 666
 667   * Created the appropriate .adoc files in the docs repository (or their own
 668     repository if the tooling is available)
 669   * Have an outline for the expected documentation in those .adoc files
 670     including the relevant (sub)sections and a sentence or two explaining what
 671     will go there
 672
 673     * Obviusly, providing actual documentation in the (sub)sections is
 674       encouraged and meets this requirement
 675
 676   * Milestone readout should include
 677
 678     #. the list of kinds of documentation
 679     #. the list of corresponding .adoc files and their location, e.g., repo and
 680        path
 681     #. the list of commits creating those .adoc files
 682     #. the current word counts of those .adoc files
 683
 684 * **M4:** Documentation Continues
 685
 686   * The readout at M4 should include the word counts of all .adoc files with
 687     links to commits
 688   * The goal is to have draft documentation complete so that the documentation
 689     group can comment on it.
 690
 691 * **M5:** Documentation Complete
 692
 693   * All (sub)sections in all .adoc files have complete, readable, usable content.
 694   * Ideally, there should have been some interaction with the documentation
 695     group about any suggested edits and enhancements
 696
 697 * **RC2:** Release notes
 698
 699   * Projects must provide release notes as .adoc pushed to integration (or
 700     locally in the project's repository if the tooling is developed)
 701
 702
 703 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
 704 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 705 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
 706 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
 707 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
 708 .. _Pandoc: http://pandoc.org/
 709 .. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips