• From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Topic: WIKI

Has any thought been given to the implementation of  Wiki to provide the opportunity for regular users to develop an up-to-date reference for Front Accounting? 

One of my frustrations is the lack of documentation.  I recognise that the developers don't have the time to keep this up to date, but with the implementation of a Wiki all the great hints written in the forum could be transferred by the Topic instigators on to the Wiki to develop an easy reference manual.  Users could also add their own info gained through their experience. Searching the forum for solutions is often difficult. 

Or maybe this has already been tried or someone has a better alternative?

  • Registered: 12/25/2007
  • Posts: 2,448

Re: WIKI

We have wiki module in download section, which is only wiki skeleton without any usable FA info. I guess that nobody in community had enough free resources to write some documentation in this form. But this wiki was designed rather as context help than general HOWTO guide.

I personally have small experience in configuring wikis, but maybe you can advice us which one would be good for FA? Also if you have some ideas and free time to entry initial info on FA wiki, I think we could experimentally establish it to check how it works for the community.

Janusz

  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

No experience myself with wiki at this stage but will have a look around.  It would be great to have one available to the community I would think.

Anyone else with any thoughts?

  • alvin
  • Senior Member
  • Offline
  • From: USA, Guatemala, Honduras
  • Registered: 05/20/2008
  • Posts: 301

Re: WIKI

I too think it is time for a wiki...  There is a lot of howto in this forum, and it should be brought forward to a wiki.

I think http://www.mediawiki.org/ would be good.  Put it in a sub domain (wiki.frontaccounting.com) To start just strip out all the howto in this forum and put it in the wiki. I maybe could find a little time to help...

AM

"The roots of education are bitter, but the fruit is sweet."  - Aristotle.
  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

I have loaded the Wiki Module on my test server.  It uses PMwiki which seems to be a pretty good choice:
http://moinmo.in/WikiEngineComparison
As that is already set up for Frontaccounting it might be the sensible way to go rather that reinventing the wheel?

  • Registered: 12/25/2007
  • Posts: 2,448

Re: WIKI

We are talking about two different applications of wiki. The Pmwiki integrated with FA is good for context help informations for FA users, but not for development/general information exchange, I think. Anybody can write context help in pmwiki and send to  developers team for placing it on FA download page - nothing more than wiki module for FA (and a lot of free time for write the content) is needed.

I will ask our site administrator about the wiki option.

Janusz

  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

Perhaps the PMwiki would be suitable for both purposes - making sharing of data , and thus timesaving, an option

8 Reply by p2409 (edited by p2409 10/06/2009 01:39:02 pm)

  • p2409
  • Senior Member
  • Offline
  • From: Australia
  • Registered: 12/11/2008
  • Posts: 127

Re: WIKI

docuwiki is simple and good too, with a very basic markup coding structure. IMHO the pages looks a bit friendlier to users than mediawiki. Either way, it's going to be the content that is important, but before the content, it would be good to agree on a STRUCTURE, especially of the pmwiki that is embedded in the system. What do people think? Structure here means a 'template' layout that all wiki items would adhere too.

I'm happy to kick off an write an article for the wiki: first of all though, what are people's thoughts on the most valuable, 'chunkable' FA topic. Preferably one that a) confuses people, b) is important, c) gets used alot and d) has not much or no info available presently? My first port of call might be describing the differences in the methods for handling sales ie. do a Sales Order, then a Delivery, then an Invoice vs. just doing all three in one hit as a direct invoice. This was confusing for me when I started using FA, but makes sense now.

I want to reiterate itronics point above: keep the 'how to's' in the system wiki, and the conceptual stuff in the online web-based wiki.

PS. To use the pmwiki successfully on a PHP version > 5.3 and get rid of all the deprecated error messages that prevent you from seeing the screen,  you will probably want to change line 20 in /modules/wiki/pmwiki.php from:
error_reporting(E_ALL ^ E_NOTICE);     
to
error_reporting(E_ALL ^ E_NOTICE ^ E_DEPRECATED);
ie. report ALL errors EXCEPT Notices EXCEPT Deprecated

  • p2409
  • Senior Member
  • Offline
  • From: Australia
  • Registered: 12/11/2008
  • Posts: 127

Re: WIKI

OK guys: here's a very basic Wiki entry for a random topic to give you a proof of concept flavour of how the online wiki might work. It's for the 'Search Template for Invoicing' page.

Steps:
1. Install the wiki module per instructions. You may have to change some permissions to keep things going (some of my directories/files were unwriteable after install)

2. Click on the Search Invoice Template page link (sales - Template for Invoicing)

3. In the wiki click on
(Create Help.SearchInvoiceTemplate)
Again, fix permissions if you have to.

4. Enter the following example text:

Purpose:
Often will you want to create similar invoices again and again. Rather than re-keying new invoices from scratch, Front Accounting lets you mark certain invoices as 'templates' and then use these templates to create new invoices with most of the information already filled in. This saves time by removing the need to re-enter all invoice information from scratch.

How to use:
Any invoice already marked as an invoice 'Template' will appear on this 'Search Template for Invoicing' page, based on the search criteria you enter at the top of the page. You can search on invoice number, location or item to find an invoice to copy. After clicking 'search' you'll see a matching list of invoices. From this list you can then choose the one you wish to copy and re-use by clicking the page-arrow image at the end of the row (next to the currency column). This will take you to the 'Sales Order Entry' screen where you can change the necessary details (customer, dates, items and delivery details) and create a new invoice by clicking the 'Place Invoice' button. To cancel, click the cancel invoice button, or return to the previous 'Search Template for Invoicing' screen by clicking 'back'.

Extra Notes:
Please note that you only can only template invoices that were originally marked as 'templated' when you created the original invoice. Unmarked invoices do not appear in the 'Search Template for Invoicing' page list.

------end of text------

Now you should have a working wiki page - get it again by clicking the Search Template Invoice link, and then the help question mark at the top right of the frame.

Note I didn't put in any formatting, and I'm not sure I got the functionality 100% right either, but it's more a proof of concept.

Let's have a discussion now about the general layout we'd like for each entry (it's so important to try to keep these consistent). For starters, I used 'Purpose', then 'How to use', then 'Extra notes'. Ideally EVERY SINGLE wiki page would follow a consistent format, as this is critical in imparting system knowledge to users. If we can agree on one, we can then publish this so people can stick to it. The alternative is to have a hotchpotch of layouts which would be pretty much  useless for quick referencing on how to use the system. We also need some 'rules' on the articles. Here are some examples I thought of:
- no simply rehashing the field names (you know the sort of useless documentation I'm talking about: see just about anything in doxygen).
- good plain English or whatever language the wiki is in (native speakers can fix any contributions I'm sure)
- Always addresses the 'why am I on this page' through the purpose paragraph
- Doesn't rehash obvious, system consistent processes in detail ie. don't have to rehash how to fill in a search screen each time - this is consistent throughout FA.

OK - that's my thoughts - over to you. Feel free to change/tear apart - it's ok I can take it!

Cheers
Pete

10 Reply by waverider (edited by waverider 10/07/2009 11:18:06 am)

  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

p2409 wrote:

Either way, it's going to be the content that is important, but before the content, it would be good to agree on a STRUCTURE, especially of the pmwiki that is embedded in the system. What do people think? Structure here means a 'template' layout that all wiki items would adhere too.

Yes, couldn't agree more - structure and conventions eg menu path notation- Sales>Customer and Sales Reports>Price Lists

I'm happy to kick off an write an article for the wiki: first of all though, what are people's thoughts on the most valuable, 'chunkable' FA topic. Preferably one that a) confuses people, b) is important, c) gets used a lot and d) has not much or no info available presently? My first port of call might be describing the differences in the methods for handling sales ie. do a Sales Order, then a Delivery, then an Invoice vs. just doing all three in one hit as a direct invoice. This was confusing for me when I started using FA, but makes sense now.

That sounds great to me - I'm still confused :-)
Someone who is very familiar with recurring queries on the forum would no doubt be able to come up with a series of topics.  Then perhaps other forum users could take on one of these and produce a page outlining the solution/solutions presented there. If every forum user took on one topic (hopeful I know) there would soon be a body of entries to get things going.

PS. To use the pmwiki successfully on a PHP version > 5.3 and get rid of all the deprecated error messages that prevent you from seeing the screen,  you will probably want to change line 20 in /modules/wiki/pmwiki.php from:
error_reporting(E_ALL ^ E_NOTICE);     
to
error_reporting(E_ALL ^ E_NOTICE ^ E_DEPRECATED);
ie. report ALL errors EXCEPT Notices EXCEPT Deprecated

This information should be in a Wiki - maybe we could start one ;-)

Is there any reason that the Help Wiki couldn't be included as a permanent module in  each upgrade rather than an addon as it is now?  That way all the latest submitted Help information would be included - and even some new /changed information as a result of altered processes. There should also be a process for easily updating the Help information on a regular basis - or maybe that is already in place?

  • Registered: 12/25/2007
  • Posts: 2,448

Re: WIKI

Is there any reason that the Help Wiki couldn't be included as a permanent module in  each upgrade rather than an addon as it is now?  That way all the latest submitted Help information would be included - and even some new /changed information as a result of altered processes. There should also be a process for easily updating the Help information on a regular basis - or maybe that is already in place?

There is only one reason: we have no wiki content since the wiki module was created, and so far we have no established method to collect job done by volunteers. When we will have less or more complete wiki content we can include it as integral part of core distribution. But adding wiki without ready content can rather discourage new users, than help them.

Janusz

  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

itronics wrote:

There is only one reason: we have no wiki content since the wiki module was created, and so far we have no established method to collect job done by volunteers. When we will have less or more complete wiki content we can include it as integral part of core distribution. But adding wiki without ready content can rather discourage new users, than help them.

Janusz

Then that gives us four issues to address:

Layout:  Decide on a template and conventions for wiki information
Collection: Come up with a method for submission and refinement of information before it is inserted into the official documentation.
Data:  Encourage users and developers to submit information.
Translation: Get translation of the information developed.

It would seem to me that:

Layout can be decided through input from as many people as possible on this forum, developers and moderators. 
Collection (including means of making submissions available for refinement by the community) is an issue for webmaster/developers
Data needs to come from the whole community - participation of all is essential.
Translation would be an ongoing issue for those with the skills needed.

A big task but one which I believe is essential for the ongoing success of Frontaccounting.  Documentation is a major issue I believe.

Can anyone refine this/ make other suggestions/come up with suggestions to maximise participation?

  • From: Australia
  • Registered: 07/09/2009
  • Posts: 54

Re: WIKI

Further to Pete's post on a Template:
I think I would add a heading for Further Information. This could provide Links to more technical or associated data which may be stored in other locations such as the 'conceptual stuff in the online web-based wiki'.

Thus we would have:

Purpose:
How to Use:
Extra Notes:
Further Information:

  • Registered: 12/25/2007
  • Posts: 2,448

Re: WIKI

I think the best method to make documentation project up and running is installation of some wiki system publicly available on our frontaccounting.com site. This have not to be pmwiki used in integrated help system, maybe another wiki system is better for this. One of things which have decided on pmwiki usage was it's simplicity and compact size suitable for integration. This is not so important on site installed wiki. More important is availability of template usage which is not supported by core pmwiki, although some plugins add this feature.

The above four part template seems to be good start point.

I cannot promise the site wiki will be available tomorrow, as our team  is currently busy with last changes to final 2.2 release, but I will do my best to make it available ASAP.

Janusz

  • alvin
  • Senior Member
  • Offline
  • From: USA, Guatemala, Honduras
  • Registered: 05/20/2008
  • Posts: 301

Re: WIKI

Yes Janusz,  the integrated pmwiki is great just the way it is, it gives admin the power to direct their users on how their system is to be used, it might be nice to have a section of the publicly available documentation wiki that a user could cut/paste as a starting point to edit their own integrated pmwiki with...

We are starting to see the same how to questions asked over and over, here in this forum. A publicly available documentation wiki will help to ease this...

I look forward to it.

AM

"The roots of education are bitter, but the fruit is sweet."  - Aristotle.
  • Registered: 12/25/2007
  • Posts: 2,448

Re: WIKI

I'm now working on make pmwiki suitable for us as an open site wiki. The requirements are a little another than for internal company wiki (authorization, layout, prepared page templates etc), so I'm not sure Pmwiki is good enough for it, but I will try.
Janusz