[gpars-dev] GPars documentation and release

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[gpars-dev] GPars documentation and release

Russel Winder-2
Currently the GrailsDoc generated guide (which we have deprecated and
are trying to replace) is rendered as a multipage document, coloured
boxes and the logo, with a mini-guide available on every page. It also
has some a green styling and a few broken links. The ASCIIDoc generated
guide (which is the replacement) is currently rendered as a single page
with a permanent left-side index, no colours, logo, and no mini-guide. I
believe we need to:

— Ensure the ASCIIDoc content is, or is more than, the GrailsDoc
content. It also needs review and sub-editing. (I believe we do not need
to reflect the changes in the GrailsDoc source, it seems illogical to
maintain both.)

— Decide whether to keep the mini-guide in the ASCIIDoc rendering, and
if yes, set about achieving it. (I am not sure how to start doing this.)

— Get the colouring of boxes and the logo into the ASCIIDoc rendering.
(I am guessing this is a CSS thing, but am not sure how to progress
this.)

— Decide whether the single page rendering of the current ASCIIDoc
rendering is better than the per-chapter rendering of the GrailsDoc.
Issues are initial load time versus usage delays. I believe I am
beginning to favour the current ASCIIDoc single page in use but is the
page going to get too big when we extend the guide more?

— Decide whether to go with the GrailsDoc or ASCIIDoc form for the 1.3.0
release which is pending.

 — Decide whether to release 1.3.0 so as to get the remoting stuff
tested in use, or whether to announce an beta/RC for people to test (*).

— Discuss how to get some motion on getting the jdk8 branch into a
usable state for a beta release (**).

I think that is about enough for one email :-)



(*) Given the user base I favour doing a release and then being prepared
to make many bug-fix releases. I believe we may need to move to a
BinTray based publishing workflow rather than a Codehaus based one as
Gradle supports BinTray much better than Codehaus as a repository, and
especially a SNAPSHOT one. However I may just be missing something. (The
current release model is via Codehaus' Nexus instance but I am not sure
it has been really tested.)


(**) Having made a start by removing all the extra166y bits from the
jdk8 branch and beginning to patch or remove the affected GPars methods,
I have stalled. With no-one else getting involved, I have found it
difficult to restart . How can we get a group of people actively working
on this to get it restarted.
--
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:[hidden email]
41 Buckmaster Road    m: +44 7770 465 077   xmpp: [hidden email]
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

signature.asc (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [gpars-dev] GPars documentation and release

Vaclav
Administrator
Hi Russel,

thank you for listing the open documentation issues. Please see my comments inlined:


— Ensure the ASCIIDoc content is, or is more than, the GrailsDoc
content. It also needs review and sub-editing. (I believe we do not need
to reflect the changes in the GrailsDoc source, it seems illogical to
maintain both.)


I agree. We may keep the grails-doc guide for one more release as a backup doc, though.
.
 
— Decide whether to keep the mini-guide in the ASCIIDoc rendering, and
if yes, set about achieving it. (I am not sure how to start doing this.)

I'd suggest creating a "quick reference" section and move the mini-guide there.


— Get the colouring of boxes and the logo into the ASCIIDoc rendering.
(I am guessing this is a CSS thing, but am not sure how to progress
this.)

We may need an external help on this one, I think.
 

— Decide whether the single page rendering of the current ASCIIDoc
rendering is better than the per-chapter rendering of the GrailsDoc.
Issues are initial load time versus usage delays. I believe I am
beginning to favour the current ASCIIDoc single page in use but is the
page going to get too big when we extend the guide more?


Let's stick with single-page design.
 
— Decide whether to go with the GrailsDoc or ASCIIDoc form for the 1.3.0
release which is pending.


We should go with ASCIIDoc, I think.

 — Decide whether to release 1.3.0 so as to get the remoting stuff
tested in use, or whether to announce an beta/RC for people to test (*).


Let's wait with a decision until Rafal gets to fixing some of the remoting issues. 

Regards,

Vaclav

Loading...