Pre-publication steps

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

Received on Friday, 11 December 2015 17:10:28 UTC