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
