[GNC-dev] Wiki FAQ Page

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

[GNC-dev] Wiki FAQ Page

GnuCash - Dev mailing list
Hello,

I am digging in to the FAQ page with an eye to rationalizing the accumulated mess. My hope is to make it easier for uers to find answers to their questions.

Currently, the structure of the page does not accurately reflect the content of the questions. For example, the section “Installation Troubleshooting” covers two broad and disparate question areas.

In addition, numerous questions have been placed haphazardly in sections to which they do not belong. For example, questions about theming do not belong under Installation (for Mac or Windows), but IMHO under “GnuCash Files and managing a GnuCash installation”, which itself would be better named “Configuring and Managing”

On a practical level, as I rearrange the FAQ on some pretty substantial levels, questions and headings on the page will be changed.

First issue: I do not see a way to see whether the wiki has any instances of links to a specific question. Clicking “What links here” only shows links to the overall FAQ page.

Second issue: many links from the mailing lists will no longer work, which may cause problems for users searching the ML archives and retrieving the stale links. How should this be handled?

Now, on a meta-level, I think the primary headings here might be better arranged as follows:

1. General Questions
  [move “Accounting Questions” to this section]
2. Installation
3. Using GnuCash [moved ahead of cunfiguring]
4. Configuring and Managing
  [Move “Customizing" questions from current section 8 to this section]
5. Troubleshooting
6. Exporting and Importing Data
7. Business Features
  [Move entire Developing GnuCash section of questions to the pages established for Developers]

I welcome input and feedback.

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] Wiki FAQ Page

John Ralls-2


> On Sep 4, 2018, at 7:43 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Hello,
>
> I am digging in to the FAQ page with an eye to rationalizing the accumulated mess. My hope is to make it easier for uers to find answers to their questions.
>
> Currently, the structure of the page does not accurately reflect the content of the questions. For example, the section “Installation Troubleshooting” covers two broad and disparate question areas.
>
> In addition, numerous questions have been placed haphazardly in sections to which they do not belong. For example, questions about theming do not belong under Installation (for Mac or Windows), but IMHO under “GnuCash Files and managing a GnuCash installation”, which itself would be better named “Configuring and Managing”
>
> On a practical level, as I rearrange the FAQ on some pretty substantial levels, questions and headings on the page will be changed.
>
> First issue: I do not see a way to see whether the wiki has any instances of links to a specific question. Clicking “What links here” only shows links to the overall FAQ page.
>
> Second issue: many links from the mailing lists will no longer work, which may cause problems for users searching the ML archives and retrieving the stale links. How should this be handled?
>
> Now, on a meta-level, I think the primary headings here might be better arranged as follows:
>
> 1. General Questions
>  [move “Accounting Questions” to this section]
> 2. Installation
> 3. Using GnuCash [moved ahead of cunfiguring]
> 4. Configuring and Managing
>  [Move “Customizing" questions from current section 8 to this section]
> 5. Troubleshooting
> 6. Exporting and Importing Data
> 7. Business Features
>  [Move entire Developing GnuCash section of questions to the pages established for Developers]
>
> I welcome input and feedback.

David,

It’s painful, but I think the only way to find links to specific anchors is to copy the (old) question and paste it into the search field. You should get a context menu, the last line of which is “contains xxx”. Click that.

Fortunately if you just move questions without rephrasing them it won’t affect the anchors at all.

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] Wiki FAQ Page

Adrien Monteleone-2
In reply to this post by GnuCash - Dev mailing list
Broken links can be handled by permanent redirects in the web server’s .htaccess file. I think Derek would be the one to add those in. If you compile the list for him to copy & paste, I’m sure that would help. The end result is someone can click the old link from the mailing list and the server will drop them in the new location.

On a content note, I suspect you could have three separate headings for “Managing GnuCash files”, “Configuring GnuCash” and “Customizing GnuCash”. I’m thinking the latter to be more geared towards things like CSS and where to put custom reports, while ‘Configuring’ is more related to tweaking the app preferences.

Regards,
Adrien

> On Sep 4, 2018, at 9:43 AM, David T. via gnucash-devel <[hidden email]> wrote:
>
> Hello,
>
> I am digging in to the FAQ page with an eye to rationalizing the accumulated mess. My hope is to make it easier for uers to find answers to their questions.
>
> Currently, the structure of the page does not accurately reflect the content of the questions. For example, the section “Installation Troubleshooting” covers two broad and disparate question areas.
>
> In addition, numerous questions have been placed haphazardly in sections to which they do not belong. For example, questions about theming do not belong under Installation (for Mac or Windows), but IMHO under “GnuCash Files and managing a GnuCash installation”, which itself would be better named “Configuring and Managing”
>
> On a practical level, as I rearrange the FAQ on some pretty substantial levels, questions and headings on the page will be changed.
>
> First issue: I do not see a way to see whether the wiki has any instances of links to a specific question. Clicking “What links here” only shows links to the overall FAQ page.
>
> Second issue: many links from the mailing lists will no longer work, which may cause problems for users searching the ML archives and retrieving the stale links. How should this be handled?
>
> Now, on a meta-level, I think the primary headings here might be better arranged as follows:
>
> 1. General Questions
>  [move “Accounting Questions” to this section]
> 2. Installation
> 3. Using GnuCash [moved ahead of cunfiguring]
> 4. Configuring and Managing
>  [Move “Customizing" questions from current section 8 to this section]
> 5. Troubleshooting
> 6. Exporting and Importing Data
> 7. Business Features
>  [Move entire Developing GnuCash section of questions to the pages established for Developers]
>
> I welcome input and feedback.
>
> David
>
>
> _______________________________________________
> 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] Wiki FAQ Page

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

at first thanks for starting with this task.

Am 04.09.2018 um 16:43 schrieb David T. via gnucash-devel:
> Now, on a meta-level, I think the primary headings here might be better arranged as follows:
>
> 1. General Questions
Perhaps the title should be more specific. Abstract
About the project, how {this page is organized [missing]}, howw to get
help (and provide required information, and give something back (from
feedback to patches).

>   [move “Accounting Questions” to this section]
Please do not, I see “Accounting Questions” more or less as "Off topic"
there are spcefic websites which can answer such questions according the
local law.

For me there is a logical sequence: Install, configure/customize, use.
> 2. Installation
> 3. Using GnuCash [moved ahead of cunfiguring]
No, before you should configure/customize your installation.

> 4. Configuring and Managing
>   [Move “Customizing" questions from current section 8 to this section]
yes

> 5. Troubleshooting
Please insert no separate Troubleshooting. It would lead to duplicate
sections.

> 6. Exporting and Importing Data
> 7. Business Features
In theory 6 & 7 are subsections of 3

>   [Move entire Developing GnuCash section of questions to the pages established for Developers]
No, there should be only one FAQ. Because it might not interest most
users , it is at the bottom.
I am pretty sure, if we would break the FAQ in parts we would end with a
bunch of duplicated sections.

> I welcome input and feedback.

As you have already started, I would prefer - like for patches - smaller
changesets (move section x into...). Diff is not very smart and it is
now almost impossible to see what really changed.

Why did you remove the table to the official docs? Many questions are
already answered there.

> David

Frank

_______________________________________________
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] Wiki FAQ Page

GnuCash - Dev mailing list
Frank,

I will begin with noting that I think that it was not entirely clear in my post that I was presenting only the top-level headings for the FAQ in this email; I was not prepared to re-align every level in the FAQ at this point.

> On Sep 4, 2018, at 4:02 PM, Frank H. Ellenberger <[hidden email]> wrote:
>
> Hi David,
>
> at first thanks for starting with this task.
>
> Am 04.09.2018 um 16:43 schrieb David T. via gnucash-devel:
>> Now, on a meta-level, I think the primary headings here might be better arranged as follows:
>>
>> 1. General Questions
> Perhaps the title should be more specific. Abstract

The existing entry is "General Frequently Asked Questions (FAQ) about GnuCash". I was merely cleaning up the heading to make it more reasonable. I have no problems with a “General Questions” section. Perhaps others have suggestions here.

> About the project, how {this page is organized [missing]}, howw to get
> help (and provide required information, and give something back (from
> feedback to patches).

About the project belongs on the website or on the main page, not as an FAQ entry.

How this page is organized *should* be clear from the main headings, which is what I am working on rationalizing.

I duplicated the first FAQ entry "How to Get Help" at the very top of the FAQ, to bring greater prominence to this issue. I additionally left this as the first entry in the FAQ. Further, there is an entry on the topic on the main wiki page. Fourth, there is a “Getting Help" link on the main web page, which links to a separate "Getting Help” page on the wiki (https://wiki.gnucash.org/wiki/Getting_Help <https://wiki.gnucash.org/wiki/Getting_Help>). Honestly, how many more pointers to the help do we need?

Noting my comment above about only presenting at the top level in this first pass, I note that there are currently 4 second level sections in “General Questions,” (“General”, Contributing, Troubleshooting and Improvements, and Mailing List Questions) and that one or more of these sections might remain going forward. I will note that many of these issues are already incorporated into other pages on the wiki—or should be, IMHO—and that as I work through the sections, I am predisposed to relying on those pages, rather than a monolithic and overly-dense FAQ page to keep track of it all.

For example, the fourth top level section on the Main page of the wiki is entirely dedicated to giving back to the project. It would be my preference to see the pages and references on the main page serve as the primary source of information on these topics, and a single brief entry on the FAQ that points the questoner to those pages.

>
>>  [move “Accounting Questions” to this section]
> Please do not, I see “Accounting Questions” more or less as "Off topic"
> there are spcefic websites which can answer such questions according the
> local law.

…except that a) general accounting questions are exceedingly common on the mailing lists, and b) these questions are already on the wiki. In the past, you have strongly advocated for including information on the wiki based on these two criteria; why change that now?

>
> For me there is a logical sequence: Install, configure/customize, use.
>> 2. Installation
>> 3. Using GnuCash [moved ahead of cunfiguring]
> No, before you should configure/customize your installation.

This could go either way—but allow me to share my reasoning behind this arrangement. For *most* users, the first hurdle they will encounter after installation will NOT be configuring and customizing their brand new accounting software package; it’s going to be to run the program and try to figure out how to do basic things with said program. Questions about how to reconfigure GnuCash (which is what most of the entries under Configuring currently are) come *after* a user has been using the program for a while. Indeed, some users NEVER attempt to load a different font for their GnuCash.

That being said, there are a large number of these questions that by rights should be eliminated as duplicates of information in more official documentation locations. The entries for Filenames and Backups are prime examples. I don’t believe I would simply remove these questions from the FAQ, since they are so perennially-asked. However, I *am* again predisposed to streamlining these questions and moving the pertinent information to a separate page in the wiki.

>
>> 4. Configuring and Managing
>>  [Move “Customizing" questions from current section 8 to this section]
> yes
>
>> 5. Troubleshooting
> Please insert no separate Troubleshooting. It would lead to duplicate
> sections.

Currently, the heading is “Installation Troubleshooting” and contains installation questions and a whole lot of other crap that doesn’t belong under Installation. *That* is an excellent recipe for duplication of information, as evidenced by the current state of information on the wiki, IMHO. Having a separate Troubleshooting section would, I believe, actually serve the end user better than what we have right now.

>
>> 6. Exporting and Importing Data
>> 7. Business Features
> In theory 6 & 7 are subsections of 3
>
>>  [Move entire Developing GnuCash section of questions to the pages established for Developers]
> No, there should be only one FAQ. Because it might not interest most
> users , it is at the bottom.
> I am pretty sure, if we would break the FAQ in parts we would end with a
> bunch of duplicated sections.

There are 7 entries in this section. I will enumerate them here and give further info under each.

1) I heard it is too hard to compile GnuCash!

Setting aside that this is not even a question, the answer here references GnuCash 1.6.0 (!!!!). It seems to me that https://wiki.gnucash.org/wiki/Building <https://wiki.gnucash.org/wiki/Building> might have a little more up-to date information on this subject.

2) Ok, what devel packages do I need in order to compile GnuCash?

Again, this is covered on other pages of the wiki. Indeed, the answer refers the user to the dependencies page.

3) Why is GnuCash written in C?

4) Why don't you rewrite GnuCash in programming language ''xyz'' so that I can contribute easily?

5) Can I read the doxygen files documenting the API offline?

and

6) Can I run GnuCash already in the build dir?

These questions do come up—on gnucash-devel. I feel that this information belongs more appropriately on the pages for development, rather than here.

Finally,

7) How do I run GnuCash under gdb and get a stack trace?

This references the external Stack Trace wiki page, but I would move it to the General Questions FAQ section, under Troubleshooting. I will note here that there is also a “Tracefile” page on the wiki; I haven’t compared the two entries, but would not be surprised to see extensive duplication of information, with one being woefully out of date.

>
>> I welcome input and feedback.
>
> As you have already started, I would prefer - like for patches - smaller
> changesets (move section x into...). Diff is not very smart and it is
> now almost impossible to see what really changed.
>

I have worked on the FAQ in a series of unitary changes thus far. Each of my commits states it purpose. I admit that the edit of the Importing section at 16:34 today states somewhat generically that it is making major changes to the section. Most of the changes in this edit were one of two types: 1) removing nonfunctional (e.g., links to user websites that are now offline) or outdated information; and 2) moving the questions around so that they followed a logical progression (Importing before Exporting; Quicken before QuickBooks before MSMoney before specific providers before generic CSV importing).

To be honest, Frank, this feels like another instance of your not trusting that I am able to make informed editorial changes to the wiki. Have you looked at the 7 edits on the FAQ I made today? Or the 9 I made last week? How are these changes “impossible to see?"


> Why did you remove the table to the official docs? Many questions are
> already answered there.
>

See my comments above about the numerous ways in which the user is directed to the documentation that is available to them. I personally think that 5 different routes is enough.


>> David
>
> Frank
>

_______________________________________________
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] Wiki FAQ Page

Derek Atkins-3
In reply to this post by Adrien Monteleone-2
I feel like MediaWiki also has a way to fix that, too, but it may only
work at a page level and not at an anchor level.

c.f. https://meta.wikimedia.org/wiki/Help:Redirect
and
https://meta.wikimedia.org/wiki/Help:Section#Section_linking_and_redirects

-derek

On Tue, September 4, 2018 12:42 pm, Adrien Monteleone wrote:

> Broken links can be handled by permanent redirects in the web server’s
> .htaccess file. I think Derek would be the one to add those in. If you
> compile the list for him to copy & paste, I’m sure that would help. The
> end result is someone can click the old link from the mailing list and the
> server will drop them in the new location.
>
> On a content note, I suspect you could have three separate headings for
> “Managing GnuCash files”, “Configuring GnuCash” and “Customizing GnuCash”.
> I’m thinking the latter to be more geared towards things like CSS and
> where to put custom reports, while ‘Configuring’ is more related to
> tweaking the app preferences.
>
> Regards,
> Adrien
>
>> On Sep 4, 2018, at 9:43 AM, David T. via gnucash-devel
>> <[hidden email]> wrote:
>>
>> Hello,
>>
>> I am digging in to the FAQ page with an eye to rationalizing the
>> accumulated mess. My hope is to make it easier for uers to find answers
>> to their questions.
>>
>> Currently, the structure of the page does not accurately reflect the
>> content of the questions. For example, the section “Installation
>> Troubleshooting” covers two broad and disparate question areas.
>>
>> In addition, numerous questions have been placed haphazardly in sections
>> to which they do not belong. For example, questions about theming do not
>> belong under Installation (for Mac or Windows), but IMHO under “GnuCash
>> Files and managing a GnuCash installation”, which itself would be better
>> named “Configuring and Managing”
>>
>> On a practical level, as I rearrange the FAQ on some pretty substantial
>> levels, questions and headings on the page will be changed.
>>
>> First issue: I do not see a way to see whether the wiki has any
>> instances of links to a specific question. Clicking “What links here”
>> only shows links to the overall FAQ page.
>>
>> Second issue: many links from the mailing lists will no longer work,
>> which may cause problems for users searching the ML archives and
>> retrieving the stale links. How should this be handled?
>>
>> Now, on a meta-level, I think the primary headings here might be better
>> arranged as follows:
>>
>> 1. General Questions
>>  [move “Accounting Questions” to this section]
>> 2. Installation
>> 3. Using GnuCash [moved ahead of cunfiguring]
>> 4. Configuring and Managing
>>  [Move “Customizing" questions from current section 8 to this section]
>> 5. Troubleshooting
>> 6. Exporting and Importing Data
>> 7. Business Features
>>  [Move entire Developing GnuCash section of questions to the pages
>> established for Developers]
>>
>> I welcome input and feedback.
>>
>> David
>>
>>
>> _______________________________________________
>> 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
>


--
       Derek Atkins                 617-623-3745
       [hidden email]             www.ihtfp.com
       Computer and Internet Security Consultant

_______________________________________________
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] Wiki FAQ Page

Adrien Monteleone-2
Yeah, those seem to be internal to the wiki, not an external broken link. But then, if the page itself isn’t changing, just the named anchor, it might not matter. The page still exists, so someone clicking an FAQ link from a mailing list message will still get dropped into the same page, but if the named anchor is not found, they’ll be focused to the top of the page rather than the intended place. Essentially then that named anchor will function as a basic page anchor which is just fine.

Regards,
Adrien

> On Sep 5, 2018, at 11:13 AM, Derek Atkins <[hidden email]> wrote:
>
> I feel like MediaWiki also has a way to fix that, too, but it may only
> work at a page level and not at an anchor level.
>
> c.f. https://meta.wikimedia.org/wiki/Help:Redirect
> and
> https://meta.wikimedia.org/wiki/Help:Section#Section_linking_and_redirects
>
> -derek
>
> On Tue, September 4, 2018 12:42 pm, Adrien Monteleone wrote:
>> Broken links can be handled by permanent redirects in the web server’s
>> .htaccess file. I think Derek would be the one to add those in. If you
>> compile the list for him to copy & paste, I’m sure that would help. The
>> end result is someone can click the old link from the mailing list and the
>> server will drop them in the new location.
>>
>> On a content note, I suspect you could have three separate headings for
>> “Managing GnuCash files”, “Configuring GnuCash” and “Customizing GnuCash”.
>> I’m thinking the latter to be more geared towards things like CSS and
>> where to put custom reports, while ‘Configuring’ is more related to
>> tweaking the app preferences.
>>
>> Regards,
>> Adrien
>>
>>> On Sep 4, 2018, at 9:43 AM, David T. via gnucash-devel
>>> <[hidden email]> wrote:
>>>
>>> Hello,
>>>
>>> I am digging in to the FAQ page with an eye to rationalizing the
>>> accumulated mess. My hope is to make it easier for uers to find answers
>>> to their questions.
>>>
>>> Currently, the structure of the page does not accurately reflect the
>>> content of the questions. For example, the section “Installation
>>> Troubleshooting” covers two broad and disparate question areas.
>>>
>>> In addition, numerous questions have been placed haphazardly in sections
>>> to which they do not belong. For example, questions about theming do not
>>> belong under Installation (for Mac or Windows), but IMHO under “GnuCash
>>> Files and managing a GnuCash installation”, which itself would be better
>>> named “Configuring and Managing”
>>>
>>> On a practical level, as I rearrange the FAQ on some pretty substantial
>>> levels, questions and headings on the page will be changed.
>>>
>>> First issue: I do not see a way to see whether the wiki has any
>>> instances of links to a specific question. Clicking “What links here”
>>> only shows links to the overall FAQ page.
>>>
>>> Second issue: many links from the mailing lists will no longer work,
>>> which may cause problems for users searching the ML archives and
>>> retrieving the stale links. How should this be handled?
>>>
>>> Now, on a meta-level, I think the primary headings here might be better
>>> arranged as follows:
>>>
>>> 1. General Questions
>>> [move “Accounting Questions” to this section]
>>> 2. Installation
>>> 3. Using GnuCash [moved ahead of cunfiguring]
>>> 4. Configuring and Managing
>>> [Move “Customizing" questions from current section 8 to this section]
>>> 5. Troubleshooting
>>> 6. Exporting and Importing Data
>>> 7. Business Features
>>> [Move entire Developing GnuCash section of questions to the pages
>>> established for Developers]
>>>
>>> I welcome input and feedback.
>>>
>>> David
>>>
>>>
>>> _______________________________________________
>>> 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
>>
>
>
> --
>       Derek Atkins                 617-623-3745
>       [hidden email]             www.ihtfp.com
>       Computer and Internet Security Consultant
>
>


_______________________________________________
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] Wiki FAQ Page

Derek Atkins
Adrien Monteleone <[hidden email]> writes:

> Yeah, those seem to be internal to the wiki, not an external broken
> link. But then, if the page itself isn’t changing, just the named
> anchor, it might not matter. The page still exists, so someone
> clicking an FAQ link from a mailing list message will still get
> dropped into the same page, but if the named anchor is not found,
> they’ll be focused to the top of the page rather than the intended
> place. Essentially then that named anchor will function as a basic
> page anchor which is just fine.

I think it would still matter.  Often we use the anchor to point users
to a specific question.

Let's assume a question gets rephrased.  That will change the anchor.
The GOOD news is that following the link to the old phrasing will still
get you to the right page, but it wont get you to the specific question
on the page (because the anchor changed).  If this happens, the user
might not know what (rephrased) question answers the question they were
trying to answer.  This is why we would want a redirect.

I SUPPOSE that I can fix this via some htaccess redirects, but it would
be better if the redirection could happen within the wiki itself.

> Regards,
> Adrien

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel