Author Topic: New Site for User and Developer API manuals  (Read 14482 times)

Offline abantecart

  • Administrator
  • Hero Member
  • *****
  • Posts: 3167
  • Karma: +229/-9
    • View Profile
    • Ideal Open Source Ecommerce Solution
New Site for User and Developer API manuals
« on: December 07, 2012, 01:38:54 PM »
We are in the process of improving our documentation site and built new easy to use interface with user manuals, developer API and community extension management site.

Goals:

- Easy to navigate manual and easy to read on mobile and regular computers (responsive)
- Collaborative, so readers can post comments
- Secure

Thinking to use WordPress.

Any ideas or suggestions?

 
We need your help to build better free open source eCommerce platform for everyone.
See how you can help

Offline Nimitz1061

  • Full Member
  • ***
  • Posts: 190
  • Karma: +21/-0
  • No matter where you go, there you are...
    • View Profile
Re: New Site for User and Developer API manuals
« Reply #1 on: December 08, 2012, 03:24:36 PM »
Don't use wordpress.

What you have is fine, application wise.

You need to settle on a document structure, then stick with it.  The current site appears to start to chunk the content down, then stuff the content into big pages.  I could rebuild that, and would be happy to help.

Possible concept:  Start a 2nd such such wiki site to handle building new documentation before each release.  Then export the content and import it into the live site to update.

David

Offline abantecart

  • Administrator
  • Hero Member
  • *****
  • Posts: 3167
  • Karma: +229/-9
    • View Profile
    • Ideal Open Source Ecommerce Solution
Re: New Site for User and Developer API manuals
« Reply #2 on: December 09, 2012, 04:08:50 PM »
Thank you for your comments and offer to help. We will give it some more thinking.

Why you do not recommend wordpress? Based on initial review it fits exactly what we need.

We need your help to build better free open source eCommerce platform for everyone.
See how you can help

Offline Nimitz1061

  • Full Member
  • ***
  • Posts: 190
  • Karma: +21/-0
  • No matter where you go, there you are...
    • View Profile
Re: New Site for User and Developer API manuals
« Reply #3 on: December 10, 2012, 08:16:31 AM »
I look to match the use of the content to the structure of the presentation.

Blogs are optimized around a journal or log type presentation - reverse chronological order is the primary presentation order.  This is not a terribly useful basis for browsing.

I know that it has become popular in recent years to consider search an adequate substitute for good in-site indexing (ie well structured navigation) but this is just false.

In short, a blog is a great place to build a development or operations "COOKBOOK" - but not a manual.

David

Offline johca

  • Newbie
  • *
  • Posts: 19
  • Karma: +5/-0
    • View Profile
Re: New Site for User and Developer API manuals
« Reply #4 on: January 13, 2015, 02:16:59 PM »
I agree with Nimitz's perspective pertinent to "good in-site indexing (ie well structured navigation)"   I tend to be a self learner and encounter much frustration in on-line manuals lacking a good site indexing.   A search is usually ineffective as it depends on knowing key words being used pertinent to a problem or solution being looked for.

For example I recently in the past week just down loaded Abantecart v1.2 (currently using a different shopping cart) and run into frustration trying to learn how to configure and manage the cart by jumping to Wikipedia, this forum, and available install and user manual.   It's also initially a bit confusing that useful extension that are desirable are browsed for in the extension store and no clear advice is disclosed if it integrates to work properly with the most current version.

For the most part I'm discovering Abantecart is robust and allows one-way-or-another easy configuration changes but some are bit more difficult with little if any clues provided.  I also like the extension capabilities or rather he ability to easily customize that extensions provide.

For example, eventually I would like to remove the donate button that currently resides besides the "Powered By AbanteCart" text in the footer.  The reason being the donate button on the fielded shopping cart I feel will confuse customers as to why and to who they are being asked to donate money.  I was actually browsing the forums looking for a solution clue to do something else when I stumbled onto  http://forum.abantecart.com/index.php/topic,2677.0.html .

Two adequate solutions were provided to remove the "Powered By AbanteCart" text.  I certainly went to the file in HTML mode and looked at the code  and even so in the new version it is on a different line and I will need to study the code a bit more to find the donate button code and either delete it or turn it off.

This points out another confusion factor of having a new version fielded while legacy versions are fielded that have significant code differences.  It mat be wise to have separate legacy version documentation and current version when the newest current version has significant code changes.

Overall Abantecart is growing in favor with me, it's just taking a bit more time and effort than I anticipated to get cart in use on my wife's (The Gift Basket Lady) website.

I just Google searched "wordPess" and the what improvement gain it is expected to provide Abantecart end-users appears unclear to me.  WordPress appears just to be another type of web content management system where the usefulness is determined by the quality of the content created that appears to be blog and discussion forum oriented rather than in itself being the manual.

I forgot to mention I searched YouTube and found how to configure Abantecart help videos.  How to video are great, but here again the usefulness of such videos is keeping them current.  The effort in managing video availability with current and correct information is not resolved by wordpress as it requires human interface more so than the "specific" platform making the videos findable and available.

Although digital and word processing technology makes paper somewhat obsolete a technical or user manual still needs to be structured with chapter content list (sections) and important word/key word/critical information word indexed.  In this regard Technical writing is performed by a technical writer and perhaps seeking out a technical writer may be more useful than playing musical forum, blog template switching as switching online format presentation still needs the effective technical manual and user manual to employ on the web for others to use.
« Last Edit: January 13, 2015, 03:34:42 PM by johca »

Offline llegrand

  • Hero Member
  • *****
  • Posts: 1275
  • Karma: +319/-2
    • View Profile
Re: New Site for User and Developer API manuals
« Reply #5 on: January 13, 2015, 03:14:53 PM »
hey,  welcome to a great cart  and don't give up too quickly -  the doc for version 1.2 will catch up.  As an Abantecart user for over a year now let me address a couple of your needs:

1.  the donate - it is a block on your template page,  just go to design  > layouts   and find the donate block on the page - usually at the bottom,  click on the field and select another block or NONE.  SAVE the page.   Now you will probably have to do that for each PAGE that shows in the left column.   But it's a simple thing to do.

2.  This is not a point you brought up,  but one I see new users struggle with and that is changing what the text is  - like on buttons,  or in screens,  etc.  AbanteCart uses xml  and they are found in the System > Localization > Language Definitions,  There is you place a portion of your "offending" text in the search box under Translation -  it will bring up all the places that appears - then you can select the one you want and change the text.  Just be sure you are on Storefront for things your customers see,  and Admin for things you see.  But it is quite a nice feature! IMO.

have fun learning a great cart!
Lee



 

Cheap Prom dresses 2018