[GNC-dev] Long Term Documentation Directions

classic Classic list List threaded Threaded
49 messages Options
123
Reply | Threaded
Open this post in threaded view
|

[GNC-dev] Long Term Documentation Directions

GnuCash - Dev mailing list
Hello,

As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare.

This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.

Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).

I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best.

Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.

Comments are welcome.

David
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

John Ralls-2


> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Hello,
>
> As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare.
>
> This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.
>
> Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).
>
> I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best.
>
> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.

I’ve no objection in principle.  Thorough preparation for such a rewrite would also include a review of the mailing list archives and the wiki.

We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.

It’s a pretty massive project, I think you’ll need to recruit a team.

Regards,
John Ralls

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Adrien Monteleone-2
David,

Count me in. (with a vote for Markdown)

Consider the idea of making the bulk of the current Help to be appendices of the new Manual. Many of those pages are simply reference lists of the menu entries.

Also, consider arranging the Manual by function rather than form. If GnuCash evolves to more closely follow the Gnome HIG, the UI is going to be very different in how it presents each function and where it appears. Arranging the manual this way will mesh nicely with that path and relieve the need to completely re-write it yet again.

Regards,
Adrien

> On Sep 8, 2018, at 10:48 AM, John Ralls <[hidden email]> wrote:
>
>
>
>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel <[hidden email]> wrote:
>>
>> Hello,
>>
>> As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare.
>>
>> This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.
>>
>> Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).
>>
>> I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best.
>>
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.
>
> I’ve no objection in principle.  Thorough preparation for such a rewrite would also include a review of the mailing list archives and the wiki.
>
> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
>
> It’s a pretty massive project, I think you’ll need to recruit a team.
>
> Regards,
> John Ralls
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Frank H. Ellenberger-3
In reply to this post by John Ralls-2
Hi,

Am 08.09.2018 um 17:48 schrieb John Ralls:

>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel <[hidden email]> wrote:
>>
>> Hello,
>>
>> As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare.
>>
>> This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.
>>
>> Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).
>>
>> I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best.
>>
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.
>
> I’ve no objection in principle.  Thorough preparation for such a rewrite would also include a review of the mailing list archives and the wiki.

-: I18N: We will loose the current translations and probably frustrate
the last translators and loose their readers.

?: Usability: Will F1 or pressing the Help button still deliver the
right content? I know it is aslo now not always th case.

Historical note: we had a GUM in version 1 and I assume there were
reasons to break it in two parts.

> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
>
> It’s a pretty massive project, I think you’ll need to recruit a team.

You might also consider to choose a more recent license. But that would
mean, you must not copy&paste.

> Regards,
> John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

GnuCash - Dev mailing list
In reply to this post by GnuCash - Dev mailing list
Frank,

You raise significant points about the effect that this might have on translations.

How would it be if these changes occurred in the course of a piecemeal approach? In other words, if I or someone else were to essentially remove the text from one document, put it in the other, and add new text at the first, would that be better?

David

On September 9, 2018, at 6:21 AM, "Frank H. Ellenberger" <[hidden email]> wrote:

Hi,

Am 08.09.2018 um 17:48 schrieb John Ralls:

>> On Sep 8, 2018, at 7:57 AM, David T. via gnucash-devel <[hidden email]> wrote:
>>
>> Hello,
>>
>> As I have noted in another thread recently, I am finding the process of updating the various documentation pieces extremely challenging—due in large part to the fragmented nature of this documentation. Different contributors have placed information on similar topics in any of a number of official locations in the GnuCash documentation realm, making the update process a circular nightmare.
>>
>> This leads to variation in content, approach, and likelihood that a user is going to locate the full information on a given subject.
>>
>> Rather than tackle each editorial task as if somehow this time it will be different, I would like to ask whether there would be support for a complete rewrite of the documentation. My idea would be to somehow merge all the content from the Guide and the Help into one huge file, and then establish a single Grand Unifying Manual that would provide users with a single source for help. Contextual help would be stripped back to only naming on screen functions, with references back to the GUM in all cases. The wiki would remain primarily for specific use cases and temporary issues. The FAQ would also point to the docs in most cases. Optionally, I would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as I think a solid Manual would obviate the need for this aspect (that, and the fact that most of the Tutorail sections are written in a “Hi, how are ya” folksie tone that I find inappropriate in formal documentation).
>>
>> I do not make this suggestion lightly—I know the complexity and difficulty of such an endeavor. However, I increasingly find that the content of the Help and Guide are so inextricably enmeshed that any attempt to clean up one will have extreme impact on the other—and attempting to shepherd these changes through piecemeal is cumbersome at best.
>>
>> Currently, the Help occupies 230 PDF pages, while the Guide weighs in at 287. That’s over 500 pages of information—a good portion of which is duplicated across the docs. Any such rewrite would entail a HUGE effort, which is why I write this email: there is no way anyone would undertake this without knowing in advance whether the community would accept such a change at the outset.
>
> I’ve no objection in principle.  Thorough preparation for such a rewrite would also include a review of the mailing list archives and the wiki.

-: I18N: We will loose the current translations and probably frustrate
the last translators and loose their readers.

?: Usability: Will F1 or pressing the Help button still deliver the
right content? I know it is aslo now not always th case.

Historical note: we had a GUM in version 1 and I assume there were
reasons to break it in two parts.

> We should resolve the source-format question (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
>
> It’s a pretty massive project, I think you’ll need to recruit a team.

You might also consider to choose a more recent license. But that would
mean, you must not copy&paste.

> Regards,
> John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

David Cousens
David,

As well as Frank's objections to rewriting, why does having one massive file
necessarily improve the structure or maintainability. This is not the case
with programming code. Docbook can include files in a far more structured
manner than the gnucash xml sources do at the moment. I would have thought
more modularization of the documentaion and some restructuring would improve
the maintainability.

I think there is perhaps more need for the tutorial approach - "How to do
this with Gnucash", particularly for newer users ,than  for  interface
button by button functional type documentation and the latter is more useful
when users have gained some experience and just want specific information on
what happens when they select a particular button or menu option.

My not particularly deep understanding of docbook  is the more the
documentation is broken down with separate headings the more searchable it
becomes and the more easily specific information can be located by using a
search. The tutorial sections tend to be more narrative/recipe like in their
construction but by crossreferencing into a functional interface description
a user can access the information when they need it and bypass it if it is
not clear what is meant.


David Cousens



-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
Op maandag 10 september 2018 10:11:11 CEST schreef David Cousens:
> David,
>
> As well as Frank's objections to rewriting, why does having one massive file
> necessarily improve the structure or maintainability. This is not the case
> with programming code. Docbook can include files in a far more structured
> manner than the gnucash xml sources do at the moment. I would have thought
> more modularization of the documentaion and some restructuring would
> improve the maintainability.
>

I don't think David T meant to put everything in one single source file. I
believe the idea is to have one single user document. So the user would only
have one link on the website to choose from or one pdf to download to get all
information. Internally this document will certainly still be composed of
multiple source files.

> I think there is perhaps more need for the tutorial approach - "How to do
> this with Gnucash", particularly for newer users ,than  for  interface
> button by button functional type documentation and the latter is more useful
> when users have gained some experience and just want specific information
> on what happens when they select a particular button or menu option.
>
I'm a big fan of use-case based documentation (or "tutorial" based). I have no
experience with writing or maintaining such documentation though. I have
attended a couple of presentations earlier this year on that topic. It's much
closer to what users are typically searching for than a formal explanation of
how each feature of gnucash works. Going into this would be a whole
conversation on its own.

But I do follow David T's observation that there's too much duplication. The
fact we currently maintain two fairly independent "manuals" is very likely
conductive to this duplication.

It doesn't necessarily have to be though. If there's a strong definition of
what goes into interface help and what goes into manual we could guard this
off.

The proposal is to make the interface help very short, with links to relevant
topics in the manual. Having links across documents is challenging so I can
follow the proposal to put it all in one document. That will save us support
questions like "the link to topic x in help topic y doesn't seem to work".

> My not particularly deep understanding of docbook  is the more the
> documentation is broken down with separate headings the more searchable it
> becomes and the more easily specific information can be located by using a
> search.

True. However this is completely tangential to how the sources are split up in
files. This searchability comes from using appropriate tags.

Regards,

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
In reply to this post by GnuCash - Dev mailing list
Op zaterdag 8 september 2018 16:57:52 CEST schreef David T. via gnucash-devel:

> Hello,
>
> As I have noted in another thread recently, I am finding the process of
> updating the various documentation pieces extremely challenging—due in
> large part to the fragmented nature of this documentation. Different
> contributors have placed information on similar topics in any of a number
> of official locations in the GnuCash documentation realm, making the update
> process a circular nightmare.
>
> This leads to variation in content, approach, and likelihood that a user is
> going to locate the full information on a given subject.
>
> Rather than tackle each editorial task as if somehow this time it will be
> different, I would like to ask whether there would be support for a
> complete rewrite of the documentation. My idea would be to somehow merge
> all the content from the Guide and the Help into one huge file, and then
> establish a single Grand Unifying Manual that would provide users with a
> single source for help. Contextual help would be stripped back to only
> naming on screen functions, with references back to the GUM in all cases.
> The wiki would remain primarily for specific use cases and temporary
> issues. The FAQ would also point to the docs in most cases. Optionally, I
> would strip out the “Tutorial” aspect of the Tutorial and Concept Guide, as
> I think a solid Manual would obviate the need for this aspect (that, and
> the fact that most of the Tutorail sections are written in a “Hi, how are
> ya” folksie tone that I find inappropriate in formal documentation).
>
The primary reasons I see for merging the documents are
- easier for the user - there's only one entry point instead of two
- easier for cross linking. In theory you can link across documents but that
will only work in well-defined conditions. Links in pdf for example won't link
to another pdf document.

So yes, I see value in merging the documents into one.

Here's my feedback on your proposal:
* Your remark about the "Hi, how are ya" folksie tone brings up an interesting
question: how do you envision the manual being written ? Is it just the tone
that's bothering you ? Or the whole idea of use-case driven documentation ? I
think this is an important point to clear out.

* Thinking a bit more on the duplication issue, I think we should distinguish
between duplication in the documentation sources and duplication in the end-
user result. Duplication in the sources are always a waste of time and a
maintenance nightmare. These should clearly be avoided. However in use-case
driven documentation duplication can be ok. Use case driven documentation
consists of recipes. Several steps in such recipes are shared across many
recipes. They can be written once and then reused several times. Can docbook
or any of the other suggested formats handle such "snippets" ?

* re-reading the proposal it looks like you still suggest to keep two
documents: one interface help, the fully stripped down document only listing
all buttons/menus and one with all formal documentation. That of course means
the linking challenge remains.

* other than that I follow your scope assignments: manual for full
documentation, wiki for specific (primarily temporary) use-cases, the FAQ
primarily a list of pointers to the proper documentation.

* and as John suggested: it's best to rally a team for this huge effort.

I'll comment separately on the translation challenge.

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

David Cousens
In reply to this post by Geert Janssens-4
Thanks Geert

My apologies to David T if I misunderstood the intention re a single
document. A single document with separate sections may help to reduce
duplication, but that mainly requires editorial effort no matter whether it
is a single document or not. it would certainly help with searches.   I also
agree that there is a lot of duplication in the two manuals.

One problem I see for Unix is that at present there doesn't appear to be a
help viewer in Unix that has support for context level help. Doc books can
obviously support defining links that can be accessed from help buttons or a
key based popup help but as far as I could see yelp has no mechanism for
linking to them.

David



-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
In reply to this post by Frank H. Ellenberger-3
Op zondag 9 september 2018 12:21:08 CEST schreef Frank H. Ellenberger:
> -: I18N: We will loose the current translations and probably frustrate
> the last translators and loose their readers.
>
Absolutely true. However I don't know if that's sufficient reason to keep the
less that satisfactory status quo.

To be honest I think this is a weakness in our tooling and one that is
preventing us from moving forward.

> ?: Usability: Will F1 or pressing the Help button still deliver the
> right content? I know it is aslo now not always th case.
>
If I read David's proposal carefully there remains some kind of interface
index document (listing all ui buttons, menu items,...). But instead of having
full documentation they would point to relevant sections in the manual.
Assuming we can make cross-linking work, this should be covered.

On the other hand if we think of our documentation more as a clever
composition of documentation snippets, we could also opt to compose help
information from the same snippets that are used to compose the full manual.
That's theory of course. I don't know if this would be possible in practice.

> Historical note: we had a GUM in version 1 and I assume there were
> reasons to break it in two parts.
>
> > We should resolve the source-format question
> > (Docbook/Asciidoc/Docx/Markdown) before beginning actual writing.
> >

Yes, we should (the list of flavors is endless by the way, I just ran into
reStructuredText, yet another variation on the theme).

And even before that we should think in more detail on how to organize our
documentation. What structure can we come up with that works for all
contributors ? How to keep it manageable ? How to make it easy to use ?

I understand direct interaction with git is a hurdle for documentation
contributors. I still don't have a good enough alternative so far.

And then back to translations. We have experimented with two methods so far:
- each translator manually copies files from the English documentation,
directly translates that file itself and commits the result the the proper
language directory.
- let gettext extract all translatable strings and offer the translator a
message catalog to translate.

Both methods have advantages and drawbacks.
Method 1:
+ users will only get content in their language
- however that may be very incomplete (only the parts of the manual that are
translated are presented to the user)
- it is very difficult for translators to update existing translations because
it's hard to determine what has changed in the English language

Method 2:
+ will always provide the full documentation to the user
- large parts can be in English instead of their native language.
- documentation updates in the English language directly affect the translated
document. For example if a paragraph has been translated and someone adds a
comma in the the English version of the paragraph, the translated
documentation will now show the English version instead of the native one.
+ this pickiness does help translators to easily spot which translations need
updating

The question is, which is worse ? From a translator's point of view I would
think the second method would be more maintainable. However how do non-native-
English users perceive a document with mixed languages ?

Again I think better tooling can help here as well. A few examples

- when composing/building the final document in method 2 we could temporarily
remove "fuzzy" markers so that "almost good" translations are still shown to
the user.

- again for method 2 we could annotate all improperly translated sections such
that the final document has "Missing Translation" tags and a pointer to invite
readers to contribute translations.

- or even better: the online documentation should be "live" editable. The
infamous "Edit me on github" ribbons we see appear everywhere, but then
better. Ideally a mixture between something like the Edit me... thing and
something like Pootle's online translation editor:
http://docs.translatehouse.org/projects/pootle/en/stable-2.8.x/features/
index.html#online-translation-editor
oh and Pootle does come with git integration. Unfortunately still in beta. And
still python2.
- pootle can be very useful on the translation side of things, but it's not
helping with writing documentation itself. So while searching yet again for a
possible solution I came across https://edit.php.net/ which is an online
editor for the php documentation, which also happens to be writting in
docbook. It's based on a few other projects such as https://codemirror.net/ an
online text editor for lots of languages including markdown, reStructuredText
and xml. I suspect the php team combined this with a few other bits to make it
a docbook parser with helpful elements such as an acronym browser and an
entity browser, syntax checking,...
- In the same category there are other online editors such as
  * https://dillinger.io/ (Markdown, github aware)
  * https://stackedit.io/ (Markdown, github aware, emoji's ! ;p )
- Of course an online editor is not *mandatory*. We would still accept direct
PR's so anyone can use their preferred editor. But my hope is that with an
online editor we could reduce the direct git interactions.

Oh, and I don't think we should *start* with an online editor. There's enough
change going on already. However while deciding our future document format it
would be nice to consider one so we don't block ourselves upfront.

Documentation updates may be a circular nightmare, finding a way to manage it
makes us running in circles as well...

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
In reply to this post by David Cousens
Op maandag 10 september 2018 13:30:20 CEST schreef David Cousens:
> One problem I see for Unix is that at present there doesn't appear to be a
> help viewer in Unix that has support for context level help. Doc books can
> obviously support defining links that can be accessed from help buttons or a
> key based popup help but as far as I could see yelp has no mechanism for
> linking to them.

I don't understand this. Do you mean that when I click on context sensitive
help in gnucash, yelp won't show the context sensitive help for that ui
element ?

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Christopher Lam
In reply to this post by David Cousens
On Mon, 10 Sep 2018 at 19:31, David Cousens <[hidden email]>
wrote:

>
> One problem I see for Unix is that at present there doesn't appear to be a
> help viewer in Unix that has support for context level help. Doc books can
> obviously support defining links that can be accessed from help buttons or
> a
> key based popup help but as far as I could see yelp has no mechanism for
> linking to them.
>

Is there any merit to the idea of launching documentation and
context-sensitive help as a libwebkit tab?
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
Op maandag 10 september 2018 13:51:28 CEST schreef Christopher Lam:

> On Mon, 10 Sep 2018 at 19:31, David Cousens <[hidden email]>
>
> wrote:
> > One problem I see for Unix is that at present there doesn't appear to be a
> > help viewer in Unix that has support for context level help. Doc books can
> > obviously support defining links that can be accessed from help buttons or
> > a
> > key based popup help but as far as I could see yelp has no mechanism for
> > linking to them.
>
> Is there any merit to the idea of launching documentation and
> context-sensitive help as a libwebkit tab?

That is indeed what John and I have been thinking about longer term. I should
have mentioned it. Of course we'd have to provide some sensible navigation
options for the user (index, back/forward buttons). And no external links
opened directly in gnucash (that would open the door for all kinds of security
issues).

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

David Cousens
In reply to this post by Geert Janssens-4
Geert

Docbook has a mechanism for including other xlm files either by declaring an
ENTITY which maps on to the filename containing the snippet xml code. You
can then use &<entity-name> to include the file contents at any point. You
can also construct "header files" which contain the entity definitions which
can be included in files as required. There is another mechanism using
XInclude which apparently has some more desirable traits. I found a Stack
exchange post/article on it today which extolled the virtues of usng
Xinclude. I'll find it again and post a link.

The current source files could be easily merged into the one document as
each file in the two documents has an entity declared. By moving the entity
declarations from the Guide to the Help manual and similarly moving the
&entity-name> lines in the gnucash-guide.xml  into the gnucash-help.xml file
then moving the Guide source files in with the Help source files, they would
become one document (needing some major rearrangement of course).

 An initial rearrangement looks possible by just rearranging the order of
the &<entity-name> statements. At the moment each file is a chapter and is
imported by the above statements.

A full rearrangement would require breaking the chapters  down into snippets
and then including them where required or in some cases just providing a
link back to where the snippet is first included.

David Cousens




-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

David Cousens
In reply to this post by Geert Janssens-4
Geert,

Is there not perhaps a way to leverage Google translate as a first pass to
translate text. The result may not be colloquial and produce some
interesting results. I have used it for Russian to English translations and
it doesn't do too bad a job.
https://translate.google.com/toolkit/docupload?hl=en

David



-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

David Cousens
In reply to this post by David Cousens
XInclude reference also modular files:

 http://sagehill.net/docbookxsl/ModularDoc.html. It should just require
using a switch  on xsltproc --xinclude when building
David



-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
David Cousens
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Geert Janssens-4
In reply to this post by David Cousens
Op maandag 10 september 2018 15:26:19 CEST schreef David Cousens:
> Geert,
>
> Is there not perhaps a way to leverage Google translate as a first pass to
> translate text. The result may not be colloquial and produce some
> interesting results. I have used it for Russian to English translations and
> it doesn't do too bad a job.
> https://translate.google.com/toolkit/docupload?hl=en
>
> David

Pootle integrates this. It could indeed be one way to jump start translations.
The technical challenges would be
- decide when to run google translate. That is how do we distinguish between
accurate real-translator-generated translations and translations that would
benefit from a google automatic translation. And the granularity can't be
language. It needs to be evaluated for each and every translatable chunk (a
paragraph? a chapter? Depends on how we decide to subdivide translatable
text).
- how clever is google translate to leave metadata/markup untouched ?
- how to automate this ?

Geert


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

GnuCash - Dev mailing list
In reply to this post by David Cousens
Dear All,

I reply to this message (even though it lacks the previous discussions for context), as it is the latest in the thread. I will, however, try to take on some of the issues that have gotten raised. I apologize for the length and density of the reply.

With regard to translations, I am not informed enough of any of the issues involved to offer any insight. I defer to those who can speak more than one language using complete sentences (rather than a combination of misconjugated verbs, incorrect formality modes, and gestures not intended to be rude in any way). ;)

With regard to the idea of using multiple back end XML files, Geert is right that I was not talking about removing multiple back end source files (although I will note that having data fragmented in the sources seems to lead to duplication of content and effort, as different writers conceptualize the proper location for a given piece of information in different ways). My goal is to unify the narrative help into one sequence and reduce duplication and overlap. Bringing all the source XML files into one Frankenstein sequence might be a way to see the future pain, but I imagine that any such amalgamation would only exist for the editorial process; any final product would in all likelihood bear only limited similarity to this documentation monster.

As might be expected from my sending in a generic bombshell, there has been a lively discussion touching on a number of different aspects of the documentation.

At the core, my proposal has the goal of making clearer the primary purposes of the different types of documentation, and working to ensure that information gets placed in the proper place, and only the proper place.

The article at https://pronovix.com/blog/overview-context-sensitive-and-embedded-help-formats <https://pronovix.com/blog/overview-context-sensitive-and-embedded-help-formats> focuses on web modalities, but the background analysis of user assistance-seeking behavior is intriguing.

Currently, there is a lack of clarity in the GnuCash community on the roles of the different documentation, and it crops up repeatedly. Questions of appropriate content for the wiki, of whether information belongs in the Help or the Guide, etc. are all indicative of this underlying problem.

*** My Documentation Manifesto ***
1. The Concept Guide should be the primary informational document.
2. The Help should provide specific information on the functions that a given on screen element serves—i.e., Contextual Help.
3. The wiki should give technical information and information that is only applicable to specific user situations.

With these three statements, a number of results follow.

First, the Guide would contain most of the narrative, explanatory text covering how GnuCash works, and how to manage most common accounting situations. Next, the Help would be stripped back substantially, with most of the narrative content that currently resides in the Help migrated to the Guide. Third, the Tutorial aspects of the documentation would reside on the wiki. More on the Tutorial issue later.

My goal is to eliminate the situation where we document Online Banking [or Reconciliation, or Account Types, or Loans, or Investments, or… you get the idea] in every spot in the GnuCash documentation, and, just for fun, have each one differ just a little bit from the others, so that the user can’t be sure which source is the closest to accurate.

With regard to the Help, I wonder whether there is some way to use the code itself to generate context help programmatically, rather than have it be a human-edited, git-managed document. As it stands right now, the Help kind of looks like someone started out that way with lists of menus and options, but then someone else came along and started writing text to go with those lists of menus. And now we have something in between. Having a programmatically-generated Context Help system would remove this document from the concerns of documenters, and once established, would only need modification if the interface were changed. I do not know how such a mechanism would work, but I imagine that it would require additional work in code to ensure that the proper links are embedded. I recognize that such an endeavor would be substantial for an application as complex as GnuCash, but I believe the payoff would be major.

Returning to the Tutorial issue: Geert asked me whether it was the style of the writing, or the content that bothered me. I think that the style was what first bothered me there, but as I considered it further, I felt that there were deeper issues embedded. Most fundamentally, I think that as currently written, some information about how GnuCash works is written in the *Guide* parts of the T&CG, while other aspects are embedded in the *Tutorial* parts of the T&CG. See, for example, section 3.3 of the Guide, which includes account setup information that is largely duplicated in the Help at Chapter 5, but is nowhere else in the Guide. The rest of the Guide chapter leading up to this Tutorial is all theoretical, and there is nothing else in the Guide that covers the Account creation process. This, to me, does not make sense, and will lead to an incomplete understanding of GnuCash’s features and functions. It would be preferable to have the Guide outline these features in one sequence. It is my belief that a clearly-written Guide would in fact obviate the need for much of the content currently embedded in Tutorial sections.

I would MUCH prefer to have Tutorial aspects removed from the Concept Guide altogether, and have them placed somewhere else. Since a tutorial, of necessity, is more situationally-focused, I recommend putting this information on the wiki. Establishing the wiki for this information might lead to a number of such contributions to be placed there (where the burdens of git and version control are removed). The wiki could contain a much broader, richer set of tutorials that cover many more use case scenarios. Much of this sort of information could come from the lists, where users over the years have hammered out solutions to specific situations, which don’t belong in a Guide or Help, but which would be useful to a subset of GnuCash users. Handling Expense reports, managing retirement funds, addressing VAT—all could be presented on the wiki. This could also help users on gnucash-users, since so many of the questions come up cyclically (how do I handle taxes?, should I close my books?); such situations could quickly be addressed by directing the new users to the wiki page, instead of re-litigating every aspect of accounting history with regards to book closing (for example).

The idea of use-case recipes sounds rather like the “walkthrough" described in the pronovix article, which they clearly see as a specific, separate, experience. Such resources have their place, but not in the Concept Guide. Walkthroughs could use DocBook ENTITY mechanisms to cobble together snippets of steps into a single sequence, but that makes my head hurt, so I won’t be the one taking that project on.

David T.


> On Sep 10, 2018, at 9:11 AM, David Cousens <[hidden email]> wrote:
>
> Geert
>
> Docbook has a mechanism for including other xlm files either by declaring an
> ENTITY which maps on to the filename containing the snippet xml code. You
> can then use &<entity-name> to include the file contents at any point. You
> can also construct "header files" which contain the entity definitions which
> can be included in files as required. There is another mechanism using
> XInclude which apparently has some more desirable traits. I found a Stack
> exchange post/article on it today which extolled the virtues of usng
> Xinclude. I'll find it again and post a link.
>
> The current source files could be easily merged into the one document as
> each file in the two documents has an entity declared. By moving the entity
> declarations from the Guide to the Help manual and similarly moving the
> &entity-name> lines in the gnucash-guide.xml  into the gnucash-help.xml file
> then moving the Guide source files in with the Help source files, they would
> become one document (needing some major rearrangement of course).
>
> An initial rearrangement looks possible by just rearranging the order of
> the &<entity-name> statements. At the moment each file is a chapter and is
> imported by the above statements.
>
> A full rearrangement would require breaking the chapters  down into snippets
> and then including them where required or in some cases just providing a
> link back to where the snippet is first included.
>
> David Cousens
>
>
>
>
> -----
> David Cousens
> --
> Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

GnuCash - Dev mailing list
OK. In reply to my own message, I have paged through the Help and compared it to the Guide. I compiled a mapping framework from Help to the Guide, and found that this might not be as huge an undertaking as I initially thought.

Here are my thoughts:

1. Introduction to GnuCash : Delete. The single paragraph enclosed therein is covered elsewhere.
2. Using This Document & Getting Help : Delete. This information is in the Guide.
3. Getting Started : Merge into Guide 2.3 The Basics. Interface
4. GnuCash Windows & Menus Options Overview : Merge into Guide 2.3 The Basics. Interface as appropriate. Retain Menus and Context Help.
5. Setting Up, Editing & Working with Accounts : Merge into Guide 3 Accounts as appropriate, except 5.4.1.1 (Online Price Retrieval) into Guide 9.6 Investing
6. Common Transaction Operations : Merge into Guide 4 Transactions. I’ll note that the Help is more detailed than the Guide in this area
7. Business Features : Largely duplicate copy of chapter 13. Business Features.
8. Tools & Assistants : Merge into various chapters based on subject—e.g., investment-oriented assistants get put into Guide 9 Investments.
9. Reports And Charts : Delete. Guide 10 Reports covers in more detail
10. Customizing GnuCash : Add as needed to new Customization chapter following Guide chapter 4.
A. GnuCash Tips and tidbits : Delete/Move to wiki (currently consists of Finance::Quote data which is, as we all know, a fast-moving target)
B. GNU Free Documentation License

As for the Guide, there are a number of bugs outstanding that point to a future direction for the structure there, most specifically Bug 687820, so I won’t address those here, except to point out that the various appendices included there should be moved to the wiki and maintained there.

Cheers,
David

> On Sep 10, 2018, at 11:26 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Dear All,
>
> I reply to this message (even though it lacks the previous discussions for context), as it is the latest in the thread. I will, however, try to take on some of the issues that have gotten raised. I apologize for the length and density of the reply.
>
> *** My Documentation Manifesto ***
> 1. The Concept Guide should be the primary informational document.
> 2. The Help should provide specific information on the functions that a given on screen element serves—i.e., Contextual Help.
> 3. The wiki should give technical information and information that is only applicable to specific user situations.
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Long Term Documentation Directions

Frank H. Ellenberger-3
In reply to this post by GnuCash - Dev mailing list


Am 10.09.2018 um 00:32 schrieb D:
> Frank,
>
> You raise significant points about the effect that this might have on translations.
>
> How would it be if these changes occurred in the course of a piecemeal approach? In other words, if I or someone else were to essentially remove the text from one document, put it in the other, and add new text at the first, would that be better?

YES, and adding comments of the form
<!-- Translators: {Rework of|Moved from}
{Help|Guide}/<filename>:<Section ID> -->
would IMHO be very helpful.

Background:
At least I use 2 kdiff3 like editor windows. In the first displaying the
changes in C since our last translation edits. In the 2., comparing the
current english with the current german version the real work happens.
The section Ids do the synchronisation in both windows.

> David

Frank

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
123