Hi Mile
On 11 Apr 2012, at 00:28, Miles Parker wrote: Hi all,
Please see bugs below. We need to create documentation for Virgo tooling, hopefully drawing on other documentation (e.g. WTP) whenever possible. I think it would also be really neat to provide the extensive runtime documentation from within Eclipse as well.
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.
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.
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.
The LaTeX files are for design documents only and you can ignore them (unless you would like to write up the design of the tooling for posterity, in which case we'll accept almost any format?!!).
My thinking is that we should maintain all of the docs including tooling in the documents repository?
Agreed. 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.
|
