RE: UCR doc skeleton

Below my michaelS follow up of Phil's answers to my questions
Best,
Michael

-----Original Message-----
From: Phil Archer [mailto:phila@w3.org] 
Sent: Thursday, April 14, 2016 7:00 PM
To: Michael Steidl (IPTC) <mdirector@iptc.org>
Cc: 'W3C POE WG' <public-poe-wg@w3.org>
Subject: Re: UCR doc skeleton



On 14/04/2016 17:03, Michael Steidl (IPTC) wrote:
> Hi Phil,
> I think I need a guideline:
> - I had a look at the Data Shapes WG  
> https://www.w3.org/2014/data-shapes/wiki/Main_Page : from there they 
> link a W3C site UC page https://www.w3.org/TR/shacl-ucr/ and the UCR 
> page on Github as Editor's Draft - 
> http://w3c.github.io/data-shapes/data-shapes-ucr/
> - Q1: what is the relationship between the W3C site page 
> https://www.w3.org/2016/poe/wiki/Use_Cases and the Github page [2]

There's nothing automatic about it, sadly. The wiki is used, as we're using it, to gather material. Then the editor picks that up (manually) and arranges it in the doc.

michaelS: my conclusions
- the doc on Github is the publicly relevant one, the Wiki page only an internal notepad. 
- Sub question: it was said that WG-external persons may submit a UC by the email list, then it should be transferred to the "UC page" - is it requited that this UC takes two hops: Wiki page and Github or may it go directly to the Github?

> - Q2: How to edit the UCR page 1: how to split the work between my editing and the ReSpec library?

Don't touch ReSpec. Everything you need to know about what it does and how to make best use of its features (which are powerful) is at/linked from https://www.w3.org/respec/

michaelS: The User Guide - https://www.w3.org/respec/guide.html - is quite helpful. To activate the ReSpec features one has to use the HTML markup defined for it.

> - Q3: How to edit the UCR page 2: how to trigger the work of the 
> ReSpec library? (or is this implicitly triggered by some event?)
> - Q4: do I get it right that the Use Cases and the Requirements should be on a single page?

Ah, pages, I remember those ;-)

It's a single document.

michaelS: I'm able to disambiguate pages and documents - and I see that e.g. the HTML5 Recommendation document located at https://www.w3.org/TR/html5/ is made of many pages. That's why I've asked.

However, if you wish to use some dynamic features then that's OK. For example, the Spatial Data WG has a staggering 50 use cases and 57 requirements. That makes it a *very* long document. To make it more manageable, they collapse all the UCs and you click to expand (if JavaScript is disabled the default view is shown, which is with everything expanded). https://www.w3.org/TR/sdw-ucr/

>
> Note: I've set up a local POE Git repository and edited a single 
> character in the UCR index.html page - was not able to push it to the 
> W3C Github POE respository. Is this approach wrong or do I only need 
> rights for that action? (I see only you and Ivan are currently 
> collaborators.)

I need to add you to the collaborators - for which all I need is your GitHub user name.

>
> For me most essential is Q1 as currently I don't understand i/ why to have very similar pages and ii/if there is a chance to update/synchronize data from one page to the other one.

Sorry it's so manual. As editor, you get to choose how you organise and present the doc, based on what the WG decides should be its content. If you like, the wiki is an easy-to edit inbox for you where people can dump stuff. How you take it out and process it is under your control.

michaelS: what I'm not happy about is having to change the HTML markup of the Wiki to the HTML markup of ReSpec manually. This is squandering time.

HTH

Phil.


>
> Best,
> Michael
>
>
> -----Original Message-----
> From: Phil Archer [mailto:phila@w3.org]
> Sent: Thursday, April 14, 2016 1:55 PM
> To: Michael Steidl (IPTC) <mdirector@iptc.org>
> Cc: W3C POE WG <public-poe-wg@w3.org>
> Subject: UCR doc skeleton
>
> Michael - and anyone else who might be an editor of our docs at a later stage.
>
> As use cases are now coming in, you may or may not want to start working on the actual UCR doc. To help kick things off, I have created a skeleton doc in the GitHub repository [1] that can be seen as it appears to a normal person [2].
>
> The donkey work is done by the ReSpec library. This handles the version IDs, author links and W3C boiler plate. Editors just need to write the content.
>
> If you prefer to use a WYSIWYG editor, http://www.bluegriffon.org/ 
> seems to be the tool of choice for many editors. There are 101 rules 
> about how we write these docs (ids on every section, write in 
> simplified (US) English, etc.) but we can cover those over time 
> (perhaps with a separate call for editors so I can walk you through 
> some of it). The main thing is make a start :-)
>
> HTH
>
> Phil.
>
> [1] https://github.com/w3c/poe
> [2] http://w3c.github.io/poe/ucr/
>
>

-- 


Phil Archer
W3C Data Activity Lead
http://www.w3.org/2013/data/

http://philarcher.org
+44 (0)7887 767755
@philarcher1

Received on Friday, 15 April 2016 06:17:16 UTC