dhis2-documenters team mailing list archive

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

Hi Jens,
This sounds like a good way forward. The mechanism in DocBook to create
hyperlinks within the document is to use a "xref" element.
http://www.docbook.org/tdg/en/html/xref.html

In terms of linking in the application ( I do not know the details here, but
you can consult Lars on how he transforms the DocBook into the inline help),
in the document source  each section can have an ID.

  <section id="dataBrowser">

Somehow, the DocBook XML is transformed, and then imported into the
application using these IDs and through appropriate references in the
application. The text in the manual, is the same as the text in the
application, without screen shots, and with some edits. So, when sections
are labelled with an ID, they can also be used to cross-reference to another
point in the document. So, if you were creating some health task, you could
use an xref do cross-reference to a specific point in the detailed technical
user manual by using the ID. So, yes, in theory, all three elements could be
cross referenced, although currently there is no way to get from the
application, back to the user manual, but this might be something we could
consider doing.

Not sure if this makes sense in a mail, but it is easy to do when you are
writing the documents. :)


Best regards,
Jason


2011/6/12 Jens Johan Kaasbøll <jensj@xxxxxxxxxx>

> Jason,
> I agree that the visualisation of data and reports issue need a more
> thorough text which could accomany trainig courses. I still think that we
> should supply some short guidance within the system based on health tasks,
> so that users won’t have to look up in manuals, which they hardly do in any
> case.  Such guidance could link to the appropriate place in the user manual
> and to a health related text.
> This would imply a design where there is the existing technical manual, a
> new health related text, and the system. And the three should be
> hyperlinked, Feasible?
> I totally algree on the idea of DocBook for implementation. The examples
> made were prototypes and not intended for anything else.
>
> Jens K
>
>
> On Fri, 10 Jun 2011 20:33:06 +0200, Jason Pickering <
> jason.p.pickering@xxxxxxxxx> wrote:
>
>> Hi Jens,
>>
>> I took a look at one of the documents you sent. Coming from an
>> academic background as an engineer, I spent a lot of time in my early
>> days using expensive pieces of equipment with thick user manuals.It
>> was not always clear to me why.  I think what you have started to
>> write is more of a practical laboratory exercise manual. Right now,
>> what we have is a basic operators manual  (What button do I press to
>> use this mass spectrometer?) , but it says nothing about how to
>> interpret the results, or how to use it to solve a particular problem.
>> Personally, I think we may need to go a lot further, and specify why
>> certain graphs/reports need to look the way they do. Why use a
>> choropleth map at all? What is the significance of such an output and
>> when should it be used? Which output do we need to answer a given
>> question in the most effective way? A map? A table? Some other type of
>> report? These questions are far from clear from either the user manual
>> or the document you have shared.
>>
>> I have long been a critic of the approach of "give them a Pivot Table
>> and it will solve all of their problems". It has not worked in several
>> places I have been and part of the reason is that people who need to
>> look at the data do not always know necessarily how data should be
>> visualized. They may be capable in interpreting "canned reports" or
>> dashboards which have been created by people familiar with data
>> visualization techniques and M&E, but may not be capable of creating
>> them themselves. I think what you have started is a sorely need
>> end-user training manual and exercise book. I peursonally think that
>> the use of the sample data set, where possible, would be ideal, as it
>> would allow standardized training materials to be developed. And of
>> course (and you knew I was going to say this) I think it should be
>> written in DocBook and committed to the documentation branch. Creating
>> Word, HTML and PDF is simple from DocBook but not the other way
>> around.
>>
>> Just a few thoughts.
>>
>> Good work. Keep it up.
>>
>> Best regards,
>> Jason
>>
>> 2011/6/10 Jens Johan Kaasbøll
>>  Obviously no success. Use the web links below instead
>>
>>  On Fri, 10 Jun 2011 14:38:23 +0200, Jens Johan Kaasbøll  wrote:
>>
>>  Seems like the attachments did not come through, even if they are in
>>  my Sent box. Strange. Try again.
>>
>>  During discussions on user learning in Tanzania, two issues came up.
>> First, users struggle with finding out how to generate reports for
>> their health management tasks. Second, many are confused as to aspects
>> of the overall structure of the HMIS, including both health
>> information and DHIS.
>>  Problems of coupling the DHIS functionality to health tasks may be
>> eased through changes in the user interface and documentation. Pushing
>> the Reports choice under Services takes you to a page void of health
>> tasks. For instance, the explanation of Chart is
>>  “View and add charts. Charts are based on indicators and either
>> organisation units or periods.”
>>  If we rather start with health tasks, we could for example write:
>>  “To get an overview of the facilities in your area for a health
>> service, choose Charts.”
>>  Likewise, manuals and slides could also be designed based on health
>> tasks, see attached drafts. These drafts also includes examples of how
>> the structures, components, concepts and principles of DHIS and HMIS
>> could be presented. The drafts are for slides
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestSlides.ppt
>> [3]
>>
>>
>>  and for a document which is closer to a textbook than a manual.
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestTextbook.doc
>> [4]
>>
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestTextbookAnnotated.pdf
>> [5]
>>
>>
>>  Shorter versions could also appear as instructions on the right part
>> of the screen as context-sensitive help when running the DHIS,
>> possibly as videos.
>>  Are there any opinions on these matters?
>>  Is it worthwhile trying to design documentaiton in this way?
>>  Managing documentation of the same thing for different media begs for
>> a more systematic way of storing and generating it than the Office
>> files I produced. This is another, but related topic for discussion.
>>  Regards,
>>  Jens Kaasbøll
>>
>>  _______________________________________________
>>  Mailing list: https://launchpad.net/~dhis2-documenters [6]
>>  Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx [7]
>>  Unsubscribe : https://launchpad.net/~dhis2-documenters [8]
>>  More help   : https://help.launchpad.net/ListHelp [9]
>>
>>
>>
>> Links:
>> ------
>> [1] mailto:jensj@xxxxxxxxxx
>> [2] mailto:jensj@xxxxxxxxxx
>> [3]
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestSlides.ppt
>> [4]
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestTextbook.doc
>> [5]
>>
>>
>>
>> http://www.uio.no/studier/emner/matnat/ifi/INF3280/v11/ChartReportTestTextbookAnnotated.pdf
>> [6] https://launchpad.net/~dhis2-documenters
>> [7] mailto:dhis2-documenters@xxxxxxxxxxxxxxxxxxx
>> [8] https://launchpad.net/~dhis2-documenters
>> [9] https://help.launchpad.net/ListHelp
>>
>
>