Re: [dpdk-dev] [PATCH 2/3] doc: added guidelines on dpdk documentation

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Thursday, July 2, 2015 5:21 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH 2/3] doc: added guidelines on dpdk
> documentation
>
> Good idea to have guidelines for doc.
> But I think the submission guidelines shouldn't be specific to doc.
> Could you move it to a contributing.rst file?
> Guidelines from the website could be moved there.

Hi Thomas,

I've removed the doc contributing guidelines and will resubmit at a later stage reworked as a more general contribution guidelines based on the information on dpdk.org.

Other comments have been integrated in V2 apart from the one below.


> > +* The use of a label is preferred since it works across files and
> > +will still
> > +  work if the header text changes.
> 
> Artificial labels are a bit ugly.
> If a header change, there will be an error for the link, right?

Most RST directives are ugly. Labels have the advantage of being explicit, and from what I can see, are widely used. Here are the recommendations from the Sphinx guide:

    Using ref is advised over standard reStructuredText links to
    sections (like `Section title`_) because it works across
    files, when section headings are changed, and for all
    builders that support cross-references.

    http://sphinx-doc.org/markup/inline.html#ref-role

John.
--