dhis2-documenters team mailing list archive

[Jason Pickering <jason.p.pickering@xxxxxxxxx>]

Hi Bob and Rachel,

Good to see we are discussing this and I think we should try and keep an
open discussion about what is best for the project. If we roll things back
a few years, there was no documentation. We discussed some alternatives on
this list, and came to a common decision (disclaimer: I suggested it) that
we use DocBook. It seemed like a good alternative at the time. There was a
decent editor (Serna) which was free, and it solved many problems with less
structured formats like WIkis and Word. Some years have gone by, and the
docs have lumbered along, and I think its a great initiative on the part of
University of Oslo to hire two full time technical writers.

Having said all of that, I hope we do not devolve into framework wars or
get distracted by too many things. The content of the docs need to be
improved. I think that is the problem we are trying ultimately to solve. To
provide better more useful documentation to users of the software.

A few points I differ with you both on a few points.

1) I have added a script in the last commit to clean the plug Serna leaves
as comments. They have been there for years and no one has seemed to
notice, but we can get rid of them now pretty easily.

2) Serna is still under active development, its just commercial. I think in
the spirit of the project, we should not demand anyone to not use a
particular tool, even if is not under active development. I like Serna. Its
simple and gets the job done. I like the feel of using a WYSIWYG editor,
even though emacs or Oxygen might be better tools. Its simply my preference
and I will continue to use it. But, your point about the unsightly comments
is well taken, so I have tried to rectify that now.

3) The main reason for not moving on to a newer version was
a) It was not needed. We use a very small subset of docbooks features, and
there was no need to move to a newer version.
b) Some dependencies of Docbook 4.5 (Serna supports this version) and 5.0
were not publicly available in a maven repor at the time the POM was
written. 4.4 was and it met our needs, and there has been no compelling
reason to upgrade.

4) We discussed this last year at the experts academy and I think the
consensus was we would stick with DocBook, but continue to look for
potentially better solutions. Proprietary solutions were not considered,
and I think would really be against the spirit of the project.

Anyway, I think it would be best to table the discussion of some major
change of new frameworks until we can discuss further in Oslo at the
academy, with the community about what the most appropriate solution would
be. In the mean time, I think we should simply focus on the content. At the
point in time we need to move to something else (be it MarkDown or MadCap
or what have you), at least everything is XML and if its worth saving, it
could always be transformed somehow.

Regards,
Jason


On Thu, Apr 7, 2016 at 10:16 PM, Bob Jolliffe <bobjolliffe@xxxxxxxxx> wrote:

> On a spectrum between low-level standardized technical docbook through
> to "user friendly" (use Word), vendor-locked proprietary and patent
> encumbered technology, this one seems to fall on the far right :-)
> Not quite what I had in mind.
>
> I can see the attraction but I would be very wary to go in this direction.
>
> On 7 April 2016 at 13:52, Rachael Brooke <rachael@xxxxxxxxx> wrote:
> > Hi everyone,
> >
> > Cecilia and I have been thinking about trying out a new tool that could
> > handle big documentation projects, translation files and other
> resources. So
> > it's good timing that this issue is being raised by you.
> >
> > We were considering looking into a solution which you may know, called
> > MadCap Flare: http://www.madcapsoftware.com/products/flare/.
> >
> > If you have any other suggestions, we'd be happy to hear your thoughts.
> >
> > Thanks for bringing this up - we're investigating!
> >
> > Rachael
> >
> > On Thu, Apr 7, 2016 at 1:42 PM, Knut Staring <knutst@xxxxxxxxx> wrote:
> >>
> >> Would be good to hear from our new documentation experts (Rachael and
> >> Cecilia) on this issue (what kinds of tools they would be comfortable
> with
> >> etc).
> >>
> >> Knut
> >>
> >> On Thu, Apr 7, 2016 at 1:30 PM, Bob Jolliffe <bobjolliffe@xxxxxxxxx>
> >> wrote:
> >>>
> >>> Hi Jason, Lars
> >>>
> >>> I am not sure the link about oxygen nested comments is really
> >>> addressing the "thing".
> >>>
> >>> I agree with Lars that having the "<!-- Created by Serna Free -->"
> >>> text inserted into all our documents is ugly, wrong and misleading.
> >>> If you are using Serna Free I think it might be a simple courtesy to
> >>> just strip those comments before committing.  Of course its possible
> >>> to forget and maybe some sort of removal hook could be configured
> >>> automatically (sed, xsltproc ..) but its maybe not so hard to just
> >>> delete the line.
> >>>
> >>> I am not sure of what the problem is with oxygen encountering these
> >>> comments are though.  Maybe I also don't get the "thing" :-)  I open
> >>> the docbook files with oxygen and don't encounter a problem related to
> >>> the comment.  The docbook4 "type" seems to be immediately recognized
> >>> and I get a Docbook4 menu appear when I switch to author mode whether
> >>> the comment is there or not.  Is it an oxygen version issue (I
> >>> currently use 17.1) or is there some other issue I am missing?
> >>>
> >>> Though I think there are deeper issues at play.  First is that Serna
> >>> Free seems no longer to be maintained (as a free version).  One
> >>> consequence of this being that using it keeps us frozen in time at
> >>> docbook 4.4.  The last release of the docbook 4.x series was 4.5 back
> >>> in 2006.  The 5.0 (and now 5.1) series has been out for quite a long
> >>> time now (2009?).  AFAIK the only reason for sticking with 4.x has
> >>> been the availability of Serna Free.
> >>>
> >>> (Which is not a small thing.  The sad truth is that  another good free
> >>> candidate for docbook editing by non-technical authors hasn't ever
> >>> emerged.  Of course if you are more than a bit geeky then emacs does a
> >>> good job.  But even I don't use emacs anymore for editing docbook
> >>> documents.  I use oxygen, which is not free.)
> >>>
> >>> Two thoughts come to mind:
> >>> (i) it probably really makes sense to rejoin the (docbook) world and
> >>> move from 4.4 to 5.0.  Particularly if the now defunct Serna Free is
> >>> the only factor holding us back.  I understand that there are
> >>> transforms available to make this a painless journey.  The best
> >>> available in terms of free editing tools with a strong docbook focus
> >>> seems to be the eclipse DEP4E plugin.  Otherwise there are the
> >>> non-free tools as well as host of xml schema aware editors.
> >>> Admittedly none of these really qualify as eminently suitable for
> >>> non-technical authors so the problem isn't really completely solved,
> >>> but maybe improved slightly.
> >>>
> >>> (ii) more radically, it might be time to consider moving from docbook
> >>> altogether.  There are a host of "cool" alternatives (markdown and
> >>> friends) none of which I am fond of, but they have enthusiastic
> >>> supporters.  To me they all seem like endless reinventions of
> >>> roff/nroff/groff and certainly lack the maturity of docbook.   But
> >>> maybe the world has moved to a stage that its possible to consider
> >>> editing html5/css3 documents directly?  Certainly there is
> >>> considerable user friendly editing tools available.  And conversion to
> >>> pdf seems not to be a problem.  Though whether this would cause the
> >>> clean structure of documents to descend into anarchy I don't really
> >>> know.
> >>>
> >>> My 2 cents.  I would certainly advocate (i) above (though admit its a
> >>> strong response to just getting rid of Serna Free comments).  (ii)
> >>> frightens me quite a bit. Certainly would be a lot of work.
> >>>
> >>> In the end comes down to (i) who will do most of the documentation and
> >>> what do they like or tolerate, (ii) what effort is justified to fiddle
> >>> with what is really quite a nice looking set of existing
> >>> documentation.
> >>>
> >>> For the moment lets at least agree to keep those horrible comments out.
> >>>
> >>> Bob
> >>>
> >>> On 6 April 2016 at 11:31, Jason Pickering <jason.p.pickering@xxxxxxxxx
> >
> >>> wrote:
> >>> > For instance, perhaps this
> >>> >
> >>> > http://www.oxygenxml.com/forum/topic3658.html
> >>> >
> >>> > which seems to describe a means of getting around comments.
> >>> >
> >>> >
> >>> >
> >>> > On Wed, Apr 6, 2016 at 7:01 PM, Jason Pickering
> >>> > <jason.p.pickering@xxxxxxxxx> wrote:
> >>> >>
> >>> >> Hi Lars,
> >>> >> I think there must be a way around this, and I would not be in favor
> >>> >> at
> >>> >> all of ditching Serna. Its a good tool and not everyone has access
> to
> >>> >> a
> >>> >> relatively expensive commercial tool like Oxygen.
> >>> >>
> >>> >> Serna Free inserts this automatically unfortunately when it saves
> the
> >>> >> document, but lets look for a look around to deal with this in
> Oxygen.
> >>> >>
> >>> >> Regards,
> >>> >> Jason
> >>> >>
> >>> >>
> >>> >> On Wed, Apr 6, 2016 at 6:44 PM, Lars Helge Øverland <lars@xxxxxxxxx
> >
> >>> >> wrote:
> >>> >>>
> >>> >>> Hi,
> >>> >>>
> >>> >>> re the documentation.The Serna editor horribly inserts a
> >>> >>>
> >>> >>> <!-- Created by Serna Free -->
> >>> >>>
> >>> >>> comment in all files it creates before the DTD. This throws off
> >>> >>> Oxygen
> >>> >>> from detecting it to be a Docbook format. Lets not use Serna
> anymore
> >>> >>> or at
> >>> >>> least make sure we don't get comments in the beginning of docbook
> xml
> >>> >>> files.
> >>> >>>
> >>> >>> Lars
> >>> >>>
> >>> >>> --
> >>> >>> Lars Helge Øverland
> >>> >>> Lead developer, DHIS 2
> >>> >>> University of Oslo
> >>> >>> Skype: larshelgeoverland
> >>> >>> http://www.dhis2.org
> >>> >>>
> >>> >>>
> >>> >>> _______________________________________________
> >>> >>> Mailing list: https://launchpad.net/~dhis2-documenters
> >>> >>> Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> >>> Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> >>> More help   : https://help.launchpad.net/ListHelp
> >>> >>>
> >>> >>
> >>> >>
> >>> >>
> >>> >> --
> >>> >> Jason P. Pickering
> >>> >> email: jason.p.pickering@xxxxxxxxx
> >>> >> tel:+46764147049
> >>> >
> >>> >
> >>> >
> >>> >
> >>> > --
> >>> > Jason P. Pickering
> >>> > email: jason.p.pickering@xxxxxxxxx
> >>> > tel:+46764147049
> >>> >
> >>> > _______________________________________________
> >>> > Mailing list: https://launchpad.net/~dhis2-documenters
> >>> > Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> > Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> > More help   : https://help.launchpad.net/ListHelp
> >>> >
> >>>
> >>> _______________________________________________
> >>> Mailing list: https://launchpad.net/~dhis2-documenters
> >>> Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> More help   : https://help.launchpad.net/ListHelp
> >>
> >>
> >>
> >>
> >> --
> >> Knut Staring
> >> Dept. of Informatics, University of Oslo
> >> Norway: +4791880522
> >> Skype: knutstar
> >> http://dhis2.org
> >
> >
>



-- 
Jason P. Pickering
email: jason.p.pickering@xxxxxxxxx
tel:+46764147049