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 Referencing Sections
 237 ^^^^^^^^^^^^^^^^^^^^
 238
 239 It's pretty common to want to reference another location in the
 240 OpenDaylight documentation and it's pretty easy to do with
 241 reStructuredText. This is a quick primer, more information is in the
 242 `Sphinx section on Cross-referencing arbitrary locations
 243 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
 244
 245 Within a single document, you can reference another section simply by::
 246
 247    This is a reference to `The title of a section`_
 248
 249 Assuming that somewhere else in the same file there a is a section
 250 title something like::
 251
 252    The title of a section
 253    ^^^^^^^^^^^^^^^^^^^^^^
 254
 255 It's typically better to use ``:ref:`` syntax and labels to provide
 256 links as they work across files and are resilient to sections being
 257 renamed. First, you need to create a label something like::
 258
 259    .. _a-label:
 260
 261    The title of a section
 262    ^^^^^^^^^^^^^^^^^^^^^^
 263
 264 .. note:: The underscore (_) before the label is required.
 265
 266 Then you can reference the section anywhere by simply doing::
 267
 268     This is a reference to :ref:`a-label`
 269
 270 or::
 271
 272     This is a reference to :ref:`a section I really liked <a-label>`
 273
 274 .. note:: When using ``:ref:``-style links, you don't need a trailing
 275           underscore (_).
 276
 277 Because the labels have to be unique, it usually makes sense to prefix
 278 the labels with the project name to help share the label space, e.g.,
 279 ``sfc-user-guide`` instead of just ``user-guide``.
 280
 281 Troubleshooting
 282 ---------------
 283
 284 Nested formatting doesn't work
 285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 286
 287 As stated in the reStructuredText_ guide, inline markup for bold,
 288 italic, and fixed-width can't be nested. Further, it can't be mixed
 289 with hyperlinks, so you can't have bold text link somewhere.
 290
 291 This is tracked in a `Docutils FAQ question
 292 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
 293 but there is no clear current plan to fix this.
 294
 295 Make sure you've cloned submodules
 296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 297
 298 If you see an error like this::
 299
 300    ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
 301    Resource file '*.robot' does not exist.
 302
 303 It means that you haven't pulled down the git submodule for the
 304 integration/test project. The fastest way to do that is::
 305
 306    git submodule update --init
 307
 308 In some cases, you might wind up with submodules which are somehow
 309 out-of-sync and in that case, the easiest way to fix it is delete the
 310 submodules directory and then re-clone the submodules::
 311
 312    rm -rf docs/submodules/
 313    git submodule update --init
 314
 315 .. warning:: This will delete any local changes or information you made
 316              in the submodules. This should only be the case if you
 317              manually edited files in that directory.
 318
 319 Make sure you run tox -edocs
 320 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 321
 322 If you see an error like::
 323
 324    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)
 325    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)
 326
 327 It usually means you ran `tox` and not `tox -edocs`, which will result
 328 in running jobs inside submodules which aren't supported by the
 329 environment defined by the `requirements.txt` file in the documentation
 330 tox setup. Just run tox -edocs and it should be fine.
 331
 332 Clear your tox directory and try again
 333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 334
 335 Sometimes, tox will not detect when your ``requirements.txt`` file has
 336 changed and so will try to run things without the correct dependencies.
 337 This usually manifests as ``No module named X`` errors or
 338 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
 339 directory and building again::
 340
 341    rm -rf .tox
 342    tox -edocs
 343
 344 Builds on Read the Docs
 345 ^^^^^^^^^^^^^^^^^^^^^^^
 346
 347 It appears as though the Read the Docs builds don't automatically clear
 348 the file structure between builds and clones. The result is that you
 349 may have to clean up the state of old runs of the build script.
 350
 351 As an example, this patch:
 352 https://git.opendaylight.org/gerrit/41679
 353
 354 Finally fixed the fact that our builds for failing because they were
 355 taking too long by removing directories of generated javadoc that were
 356 present from previous runs.
 357
 358 AsciiDoc-based Documentation
 359 ============================
 360
 361 Information on the AsciiDoc tools and build system can be found here:
 362 https://wiki.opendaylight.org/view/Documentation/Tools
 363
 364 Directory Structure
 365 -------------------
 366
 367 The AsciiDoc documentation is all located in the ``manuals`` directory
 368 of the ``docs`` ``git`` repository. An example of the directory
 369 structure on June 28th, 2016 can be seen here::
 370
 371    $ tree -L 4
 372    .
 373    ├── common
 374    │   └── app_support.xml
 375    ├── developer-guide
 376    │   ├── pom.xml
 377    │   └── src
 378    │       └── main
 379    │           ├── asciidoc
 380    │           └── resources
 381    ├── getting-started-guide
 382    │   ├── pom.xml
 383    │   └── src
 384    │       └── main
 385    │           ├── asciidoc
 386    │           └── resources
 387    ├── howto-openstack
 388    │   ├── pom.xml
 389    │   └── src
 390    │       └── main
 391    │           ├── asciidoc
 392    │           └── resources
 393    ├── pom.xml
 394    ├── readme
 395    │   ├── pom.xml
 396    │   └── src
 397    │       └── main
 398    │           └── asciidoc
 399    └── user-guide
 400        ├── pom.xml
 401        └── src
 402            └── main
 403                ├── asciidoc
 404                └── resources
 405
 406 Each of the top-level directories under ``manuals`` is a whole guide by
 407 itself and it contains a ``pom.xml`` file saying how to build it, a
 408 ``src/main/asciidoc`` directory with AsciiDoc source files and a
 409 ``src/main/resources`` directory containing images.
 410
 411 Troubleshooting
 412 ---------------
 413
 414 See `AsciiDoc Tips`_ on the wiki for more information.
 415
 416 Common AsciiDoc mistakes
 417 ^^^^^^^^^^^^^^^^^^^^^^^^
 418
 419 See also `AsciiDoc Tips`_.
 420
 421 * Lists that get formatted incorrectly because of no blank line above
 422   the list.
 423 * Numbered lists that are formatted incorrectly and every bullet winds
 424   up being 1
 425
 426 Migration from AsciiDoc to ReStructuredText
 427 ===========================================
 428
 429 Automatically
 430 -------------
 431
 432 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
 433 produce DocBook as part of our build chain from AsciiDoctor. In
 434 practice, for modest-sized migrations doing things by hand works fairly
 435 well.
 436
 437 By Hand
 438 -------
 439
 440 Converting from AsciiDoc to reStructuredText is usually pretty
 441 straightforward and involves looking up the basic syntax for what you
 442 want to do by looking it up in the reStructuredText_ guide.
 443
 444 The differences are usually minor and fast to change.
 445
 446 Also, because of how fast Sphinx builds, and how fast it is to refresh
 447 the HTML documentation rapid iteration is very easy.
 448
 449 Bold/Italics/Verbatim Formatting
 450 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 451
 452 This is mostly minor syntax issues. In AsciiDoc you do inline
 453 formatting something like this::
 454
 455    *bold* _italic_ +verbatim+ `verbatim`
 456
 457 In reStructuredText, things are slightly different::
 458
 459    **bold** *italic* ``verbatim``
 460
 461 Images
 462 ^^^^^^
 463
 464 Image formats change from something like::
 465
 466    .OpenStack Architecture
 467    image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
 468
 469 To something like::
 470
 471    .. figure:: images/dlux-default.png
 472
 473 A helpful regular expression for automating the replacements is
 474 something like::
 475
 476    search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
 477    replace: $1.. figure:: images/dlux/$3\n$1   :width: $5\n\n$1   $2
 478
 479
 480 Project Documentation Requirements
 481 ==================================
 482
 483 Submitting Documentation Outlines (M3)
 484 --------------------------------------
 485
 486 #. Determine the features your project will have and which ones will be
 487    ''user-facing''.
 488
 489    * In general, a feature is user-facing if it creates functionality that a
 490      user would direction interact with.
 491    * For example, ``odl-openflowplugin-flow-services-ui`` is likely
 492      user-facing since it installs user-facing OpenFlow features, while
 493      ``odl-openflowplugin-flow-services`` is not because it provides only
 494      developer-facing features.
 495
 496 #. Determine pieces of documentation you need provide based on the features
 497    your project will have and which ones will be user-facing.
 498
 499    * The kinds of required documentation can be found below in the
 500      :ref:`requirements-for-projects` section.
 501    * Note that you might need to create multiple different documents for the
 502      same kind of documentation. For example, the controller project will
 503      likely want to have a developer section for the config subsystem as well
 504      as a for the MD-SAL.
 505
 506 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
 507 #. For each piece of documentation find the corresponding template in the docs repo.
 508
 509    * For user documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_user_guide.adoc``
 510    * For developer documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_developer_guide.adoc``
 511    * For installation documentation (if any): ``docs.git/manuals/readme/src/main/asciidoc/template_installation_guide.adoc``
 512
 513 #. Copy the template into the appropriate directory for your project.
 514
 515    * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/${project-shortname}/${feature-name}-user.adoc``
 516    * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/${project-shortname}/${feature-name}-dev.adoc``
 517    * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/${project-shortname}/${feature-name}-install.adoc``
 518
 519 #. Edit the template to fill in the outline of what you will provide using the
 520    suggestions in the template.
 521
 522    * DO NOT leave any sections blank as blank sections will cause build errors.
 523
 524 #. Link the template into the appropriate core adoc file
 525
 526    * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/bk-user-guide.adoc``
 527    * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/bk-developers-guide.adoc``
 528    * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/bk-install-guide.adoc``
 529    * Add a line like:
 530
 531      .. code-block:: none
 532
 533         include::${project-shortname}/${feature-name}-user.adoc[]
 534
 535    * Make sure there is a blank line between your include statement and any others as this prevents sections from running into each other.
 536
 537 #. Make sure the documentation project still builds.
 538
 539    * Run ``mvn clean install`` from the root of the cloned docs repo.
 540
 541      * After that, you should be able to find the PDF and HTML version of the
 542        docs. Use ``find . -name *.pdf`` to find the PDF and the HTML is
 543        always at ``target/docbkx/webhelp/${manual-name}/index.html``.
 544
 545    * The `AsciiDoc tips <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_
 546      page provide common errors and solutions.
 547    * If you still have problems e-mail the documentation group at
 548      documentation@lists.opendaylight.org
 549
 550 #. Commit and submit the patch
 551
 552    #. Commit using:
 553
 554       .. code-block:: bash
 555
 556          git add --all && git commit -sm "Documentation outline for ${project-shortname}"
 557
 558    #. Submit using:
 559
 560       .. code-block:: bash
 561
 562          git review
 563
 564       See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
 565       page if you don't have git-review installed.
 566
 567 #. Wait for the patch to be merged or to get feedback
 568
 569    * If you get feedback, make the requested changes and resubmit the patch.
 570    * When you resubmit the patch, it's helpful if you also post a +0 reply to
 571      the gerrit saying what patch set you just submitted and what you fixed in
 572      the patch set.
 573    * The documentation team will also be creating (or asking projects to
 574      create) small groups of 2-4 projects that will peer review each other's
 575      documentation. Patches which have seen a few cycles of peer review will be
 576      prioritized for review and merge by the documentation team.
 577
 578 Expected Output From Documentation Project
 579 ------------------------------------------
 580
 581 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
 582
 583 * User/Operator Guide
 584 * Developer Guide
 585 * Installation Guide
 586
 587 These guides will consist of "front matter" produced by the documentation group
 588 and the per-project/per-feature documentation provided by the projects. Note
 589 that this is intended to be who is responsible for the documentation and should
 590 not be interpreted as preventing people not normally in the documentation group
 591 from helping with "front matter" nor preventing people from the documentation
 592 group from helping with per-project/per-feature documentation.
 593
 594 Boron Project Documentation Requirements
 595 ----------------------------------------
 596
 597 .. _kinds-of-docs:
 598
 599 Kinds of Documentation
 600 ^^^^^^^^^^^^^^^^^^^^^^
 601
 602 These are the expected kinds of documentation and target audiences for each kind.
 603
 604 * **User/Operator:** for people looking to use the feature w/o writing code
 605
 606   * Should include an overview of the project/feature
 607   * Should include description of availbe configuration options and what they do
 608
 609 * **Developer:** for people looking to use the feature in code w/o modifying it
 610
 611   * Should include API documentation, e.g., enunciate for REST, Javadoc for
 612     Java, ??? for RESTCONF/models
 613
 614 * **Contributor:** for people looking to extend or modify the feature's source
 615   code
 616
 617   .. note:
 618
 619      should be documented on the wiki not in asciidoc
 620
 621 * **Installation:** for people looking for instructions to install the feature
 622   after they have downloaded the ODL release
 623
 624   .. note:
 625
 626      audience is the same as User/Operator docs
 627
 628   * For most projects, this will be just a list of top-level features and
 629     options
 630
 631     * As an example, l2switch-switch as the top-level feature with the -rest
 632       and -ui options
 633     * We'd also like them to note if the options should be checkboxes (i.e.,
 634       they can each be turned on/off independently) or a drop down (i.e., at
 635       most one can be selected)
 636     * What other top-level features in the release are incompatible with each
 637       feature
 638     * This will likely be presented as a table in the documentation and the
 639       data will likely also be consumed by automated installers/configurators/downloaders
 640
 641   * For some projects, there is extra installation instructions (for external
 642     components) and/or configuration
 643
 644     * In that case, there will be a (sub)section in the documentation
 645       describing this process.
 646
 647 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
 648   documentation
 649
 650   * Generally, these should be done as a (sub)section of either user/operator
 651     or developer documentation.
 652   * If they are especially long or complex, they may belong on their own
 653
 654 * **Release Notes:**
 655
 656   * Release notes are required as part of each project's release review. They
 657     must also be translated into AsciiDoc for inclusion in the formal
 658     documentation.
 659
 660 .. _requirements-for-projects:
 661
 662 Requirements for projects
 663 ^^^^^^^^^^^^^^^^^^^^^^^^^
 664
 665 Projects MUST do the following
 666
 667 * Provide `AsciiDoc-format <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_ documentation including
 668
 669   * Developer documentation for every feature
 670
 671     * Most projects will want to logically nest the documentation for
 672       individual features under a single project-wide chapter or section
 673     * This can be provided as a single .adoc file or multiple .adoc files if
 674       the features fall into different groups
 675     * This should start with ~300 word overview of the project and include
 676       references to any automatically-generated API documentation as well as
 677       more general developer information (see
 678       :ref:`kinds-of-docs`).
 679
 680   * User/Operator documentation for every every user-facing feature (if any)
 681
 682     * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
 683     * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
 684     * This can be provided as a single .adoc file or multiple .adoc files if the features fall into different groups
 685
 686   * Installation documentation
 687
 688     * Most projects will simply provide a list of user-facing features and
 689       options. See :ref:`kinds-of-docs` above.
 690
 691   * Release Notes (both on the wiki and AsciiDoc) as part of the release review.
 692
 693 * This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
 694
 695   * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
 696   * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
 697
 698 * Projects MUST cooperate with the documentation group on edits and enhancements to documentation
 699
 700   * 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.
 701
 702 Timeline for Deliverables from Projects
 703 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 704
 705 * **M3:** Documentation Started
 706
 707   * Identified the kinds of documentation that will be provided and for what
 708     features
 709
 710     * Release Notes are not required until release reviews at **RC2**
 711
 712   * Created the appropriate .adoc files in the docs repository (or their own
 713     repository if the tooling is available)
 714   * Have an outline for the expected documentation in those .adoc files
 715     including the relevant (sub)sections and a sentence or two explaining what
 716     will go there
 717
 718     * Obviusly, providing actual documentation in the (sub)sections is
 719       encouraged and meets this requirement
 720
 721   * Milestone readout should include
 722
 723     #. the list of kinds of documentation
 724     #. the list of corresponding .adoc files and their location, e.g., repo and
 725        path
 726     #. the list of commits creating those .adoc files
 727     #. the current word counts of those .adoc files
 728
 729 * **M4:** Documentation Continues
 730
 731   * The readout at M4 should include the word counts of all .adoc files with
 732     links to commits
 733   * The goal is to have draft documentation complete so that the documentation
 734     group can comment on it.
 735
 736 * **M5:** Documentation Complete
 737
 738   * All (sub)sections in all .adoc files have complete, readable, usable content.
 739   * Ideally, there should have been some interaction with the documentation
 740     group about any suggested edits and enhancements
 741
 742 * **RC2:** Release notes
 743
 744   * Projects must provide release notes as .adoc pushed to integration (or
 745     locally in the project's repository if the tooling is developed)
 746
 747
 748 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
 749 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 750 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
 751 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
 752 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
 753 .. _Pandoc: http://pandoc.org/
 754 .. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips