Re: Pre-publication steps

Phil,

Excellent thank you for the guidance, even though we have a ways to go on
the DUV, I feel its settling down enough to pay attention to these
publication details.

Kind regards,

Eric

On Fri, Dec 11, 2015 at 9:10 AM, Phil Archer <phila@w3.org> wrote:

> Riccardo, Eric, Newton,
>
> I think it's the three of you who are doing most work to prepare the docs
> for publication (with luck, Eric, we can vote next week to publish the DUV
> immediately after Christmas ;-) )
>
> Before publication there are a number of steps that need to be followed. I
> am happy to take on some of this as your team contact, however, I will be
> travelling Monday-Tuesday and so time is tight. Our webmaster is expecting
> a raft of publications on Thursday and so we need to be prepared.
>
> The order of these steps is not important but here's a list:
>
> 1. Spelling needs to be checked. Please run the text through a spell
> checker set to US English (warning- Europeans write 'organisation,'
> Americans write 'organization' etc.)
>
> 2. Weird thing about W3C, we give the word Web a capital W (when it refers
> to the WWW).
>
> 3. HTML must be valid. The validator is at https://validator.w3.org.
>
> Warnings are OK, actual errors are not. The most common errors are
> unclosed elements, or extra closing elements that don't match an opening
> one etc. As discussed, the <section> elements are what drives the ToC and
> numbering.
>
>
> Also, all links must resolve, so use the link checker too
> http://validator.w3.org/checklink
>
> It has a habit of reporting some URLs as unavailable but when you try them
> in the browser, they're fine. If this happens it's because the check sends
> an HTTP HEAD request, not a GET - and some servers are set up not to
> respond to HEAD requests.
>
>
> 4. Note that ReSpec does a lot of the work for you - and it does do a
> *lot* of work. For example, it writes in ids for every section and every
> heading that doesn't already have one. It also adds in RDFa markup and Web
> ARIA info. That's why the published docs have far more markup than you put
> in. If you copy and paste *from* a published doc, it will have all that in
> there and it won't do any harm, but it may surprise you to see it :-)
>
> 5. Thanks for including the change logs - they're important.
>
> 6. The ReSpec config is important of course. This is what writes in all
> the top matter. If you look at the source code of view-source:
> http://w3c.github.io/sdw/UseCases/SDWUseCasesAndRequirements.html you'll
> see all the config options, including the section on 'otherLinks'. That's
> where you can put the links to the GH repo, the Diff etc.
>
> 7. The diff! ReSpec even does that for you. Click the reSpec icon on the
> top right of the doc and choose to save. You'll see various options, one of
> which is to save the diff - and voila - you have a diff marked doc you can
> save. It refers to the URL you defined as the previous version.
>
> Then if you really want to finish the job there is our PubRules checker
> https://www.w3.org/2005/07/pubrules This checks for many things, most of
> which are handled by ReSpec, but not all. Documents that don't pass
> PubRules won't be published.
>
> You can do all this. The only thing you can't do is to install the
> documents on w3.org which I will do of course. The more of this you're
> able to do, the more chance there is of us meeting the deadline.
>
> The documents need to be installed and PubRules on Wednesday. And I need
> to send a publication request to the webmaster.
>
> I'll do my best to help between now and then of course. I'll be in a 2 day
> project meeting and so will have some ability to tune out from time to time.
>
> Phil.
>
>
>
> --
>
>
> Phil Archer
> W3C Data Activity Lead
> http://www.w3.org/2013/data/
>
> http://philarcher.org
> +44 (0)7887 767755
> @philarcher1
>