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