Re: [virgo-dev] Eclipse Help and Tooling Documentation

[Glyn Normington <gnormington@xxxxxxxxxx>]

On 12 Apr 2012, at 02:17, Miles Parker wrote:

> 
> Making a good start at this..the organization of docs is all very straightforward.
> 
> On 2012-04-11, at 12:57 AM, Glyn Normington wrote:
>> 
>> Agreed, but please make including the runtime documentation slightly lower priority than creating tooling docs as the latter is clearly where your knowledge needs capturing.
> 
> Will do. The marginal work is actually quite low as we'll need to work out the Eclipse Help publishing for the tooling-guide anyway.

Thanks.

> 
>> 
>>> 
>>> There is already some documentation for the tooling in the existing user docs (chapter 7) but I think we should consider re-organizing it. e.g. give tooling it's own high level Eclipse Docs and making a separate Guide, e.g. "Eclipse IDE Guide" . What do people think? (Alternatively, we could do some sort of docbook magic to break this out for Eclipse Help only but I do think it makes sense as a separate doc.) In general, how closely should I coordinate any such changes with the rest of the Virgo team?
>> 
>> Feel free to move material to form the new guide, but let us know which sections of the runtime docs you have edited so we can perform an editorial pass to make sure cross-references are not broken etc. Presumably the new guide should be called "Virgo IDE Guide" or "Virgo Eclipse IDE Guide" or something similar.
> 
> Internally it will be "tooling", internally I was thinking something like "Virgo Tools Guide" (at least on Eclipse side where the Eclipse part would be obvious. :)

Fine.

> 
>> 
>>> 
>>> Naturally, w'd like to follow the existing Virgo approach to generating and maintaining documentation. I've used docbook, but based on a toolchain that leverages Mylyn WikiText, i.e. editing the docs in Wikitext, then transforming them to docbook and from there to PDF, web, Eclipse Help, etc.. The Virgo toolchain is a bit different but I should be able to grok it. Is there any documentation of the documentation maintenance process? I can see that I just need to run ant doc to produce the documentation, but I'm not sure what artifacts to actually maintain for the documentation proper. I'm guessing the xml, but there are also .tex artifacts in the design-docs dir.
>> 
>> Edit the xml files and run ant doc or, equivalently, ant doc-html. We ditched PDF output as the FOP processor was inclined to go into a tight CPU spin and break the build (at least on my machine!) and proved impossible to debug.
> 
> Hmm..pdf builds just fine on my Mac. I can build it here and upload. :D (I've done a lot of doc building in last year or so so it may be that I just happen to have all of the right bits on my machine.)

The CPU spin is intermittent and prone to happen in the middle of doing a release. Often I can build the PDFs manually, but we have too many manual steps in the release process already (such as copying the docs into cvs). We aim for a release process where we invoke one script and drink coffee until it's done, including all regression testing and publishing to eclipse.org. No manual doc building or testing if we can possibly avoid it since any manual step will inevitably be omitted or screwed up by one of us at some point in the future. ;-)

> 
>> 
>>> I'm guessing I already have write access to that, but I might need to make some changes to the docs generation process / dependencies to include Eclipse docs. Does anyone have any problems with that and should I coordinate any such changes here?
>> 
>> So long as you don't break the build of the docs repo, please go ahead. Let us know if you need help or a cross-check.
> 
> OK. Why don't I put it in a branch for now, and we'll coordinate moving it into master.

Sounds good.

> 
> _______________________________________________
> virgo-dev mailing list
> virgo-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/virgo-dev