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. 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 > >>>>>> > >>>>> > >>>>> > >>>>> > >>>> > >>>> > >>> > >> > >> >
