On Wed, Dec 19, 2012 at 12:36 AM, Stephen Cameron <steve.cameron...@gmail.com> wrote: > Hi Rob, > > I agree with your points, It should be possible to create something using > the AOO Writer by borrowing the DITA concepts rather than the standard > itself, maybe by using templates. > > The key concept is to be able to generate big documents from lots of > smallish, very specifically focused, ones. This provides many advantages > (as reading an intro to DITA will make clear) but regarding managing the > 'content' development process and in the usefulness of the end result. > > Potentially the DITA open toolkit can be tweeked to accept something > different, its all XML behind the scenes in ODF I assume. >
>From another direction, maybe we can find a way to convert AOO output (in ODF format) into proper DITA? There might we away that this could be done using a combination of styles and metatags inserted into the text of the document. -Rob > > > On Wed, Dec 19, 2012 at 12:22 PM, Rob Weir <robw...@apache.org> wrote: > >> On Tue, Dec 18, 2012 at 7:15 PM, Stephen Cameron >> <steve.cameron...@gmail.com> wrote: >> > Hi, Have you ever thought of DITA as an option for AOO documentation? >> > >> > I've just started using it for documentation of some non-commercial >> > software. >> > >> > There is an FOSS resource in the DITA Open Toolkit. >> > >> > In theory the DITA concepts are resources from which is generated >> different >> > types of documentation via DITA maps. >> > >> > http://dita-ot.sourceforge.net/ >> > >> > If coders created DITA topics as feature where implemented then these >> could >> > be taken and used by people creating documentation. >> > >> > This just might overcome one of the major limitations of many open-source >> > projects, poor documentation. >> > >> >> I certainly have suggested DITA as an approach. It has the advantages >> of being able to target PDF, HTML, e-Book., etc. It also would allow >> us to do a greater degree of customization, e.g., encode what >> paragraphs are Linux-specific, etc., and then generate a guide for >> windows, another one for Linux, etc., from a single source document. >> >> However, the arguments against DITA that I've heard include: >> >> 1) Volunteers are not familiar with it. So it becomes an additional >> hurdle for contributors >> >> 2) Editing DITA via raw XML is hard, but the good DITA editors that >> make DITA editing easy are not free. >> >> 3) Since our project includes its own word processor, we should >> probably use it for producing documentation. >> >> I don't think these hurdles are impossible to overcome, but we'd need >> to figure out how to do so. >> >> IMHO learning DITA is not very hard. You don't need to be a >> programmer, for example. And knowledge of DITA is a useful market >> skill. So if we did a "call for documentation volunteers" and talked >> about this being an opportunity to gain experience with DITA, that >> might be attractive to some new volunteers. On the other hand, some >> just want to write, and not worry about a more complicated document >> preparation workflow. >> >> Regards, >> >> -Rob >> >> >> >> > >> > On Wed, Dec 19, 2012 at 10:03 AM, Keith N. McKenna < >> > keith.mcke...@comcast.net> wrote: >> > >> >> Rob Weir wrote: >> >> >> >>> On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna >> >>> <keith.mcke...@comcast.net> wrote: >> >>> >> >>>> Donald Whytock wrote: >> >>>> >> >>>>> >> >>>>> Hotkey reference pages? >> >>>>> >> >>>>> My personal preference for documentation is usually immediate-answer >> >>>>> stuff like reference pages and very specific how-tos, as opposed to >> >>>>> general guides and introductions. Perhaps that's just me coming from >> >>>>> a programming perspective. >> >>>>> >> >>>>> Don >> >>>>> >> >>>>> >> >>>> Don; >> >>>> >> >>>> Immediate answer pages are great and they serve a useful purpose. >> However >> >>>> there is also need for In depth Guides and Introductions such as the >> >>>> Getting >> >>>> Started Guides. There are still many of us that prefer to have hard >> copy >> >>>> documentation that we can highlight and mark-up as fits our learning >> >>>> styles. >> >>>> >> >>>> >> >>> With hypertext we can have both, right? Immediate answer pages that >> >>> link to in depth reference material for details, etc. >> >>> >> >>> -Rob >> >>> >> >>> Rob; >> >> >> >> That is correct. That is one nice thing about electronic documentation. >> >> >> >> Regards >> >> Keith >> >> >> >> >> >>> >> >>> Regards >> >>>> Keith >> >>>> >> >>>> On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir <robw...@apache.org> >> wrote: >> >>>>> >> >>>>>> >> >>>>>> As we wait, patiently, for the new doc list to be created, it might >> be >> >>>>>> worth having a quick discussion about priorities. >> >>>>>> >> >>>>>> I know there has been talk about "getting started" guides, perhaps >> >>>>>> done on the wiki. >> >>>>>> >> >>>>>> Another idea I had was a very targeted version of that, thinking >> >>>>>> specifically of Microsoft Office users migrating to OpenOffice. >> Would >> >>>>>> it be worth having a small guide just for them, say the "top 10" >> >>>>>> helpful hints for MS Office users, things they might find confusing >> at >> >>>>>> first. >> >>>>>> >> >>>>>> For example: >> >>>>>> >> >>>>>> 1) In Calc, the argument separator is a semi-colon, not a comma. >> >>>>>> >> >>>>>> 2) In Calc, toggling absolute address mode is done by a shift-F4, >> not >> >>>>>> an >> >>>>>> F4 >> >>>>>> >> >>>>>> OK. Maybe we end up more with 40 or 50 things like this. >> >>>>>> >> >>>>>> Would this be useful and worth trying? >> >>>>>> >> >>>>>> -Rob >> >>>>>> >> >>>>> >> >>>>> >> >>>>> >> >>>> >> >>>> >> >>> >> >> >> >> >>
