[OPEN-ILS-GENERAL] Evergreen Doc site Revamp

[Josh Stompro]

Hello Snigdha,  I like several of your suggestions.

I like the per page comments idea, I think it is a great way to get feedback that is directly attached to the source material.  We might have to deal with moderation since there will always be users that try to use any comment box they see as a way to get general technical support.

I don’t currently have a problem with how the various versions of the documentation are displayed, your way might be better.

I don’t like the idea of adding the table of contents to every page just because of the screen space it takes up.  If it can be expanded & collapsed by the user then I would have no problem with it.

Your mock up doesn’t include searching.  I would like to see changes to the search feature.  If I’m doing a search in the 2.6 documentation, I only want to see results for the 2.6 documentation.  So I would like to see the search box include scoping options that allow it to only search the current docs, all docs, all evergreen sites + irc logs + mailing list.

Josh

From: open-ils-general-bounces at list.georgialibraries.org [mailto:open-ils-general-bounces at list.georgialibraries.org] On Behalf Of Snigdha Dagar
Sent: Friday, September 26, 2014 2:11 AM
To: open-ils-general at list.georgialibraries.org
Subject: [OPEN-ILS-GENERAL] Evergreen Doc site Revamp

Hi all,

I am Snigdha, a new member of the Evergreen community. I am interested in working on the documentation project under the OPW in Evergreen. I have been interacting with Kathy and Yamil for quite some time now and with their help, have been able to understand the evergreen documentation better.

I have gone through several other open source project documentations; notably Django, QT, PHP, PostgreSQL among others; and would like to propose certain changes to the evergreen documentation organization. I have listed my ideas down here and would love to hear your feedback/suggestions.

1. I noticed that there is no difference between the PDF and HTML versions of the documentation. A PDF requires linear organization of material and is perfect as it is. It is my humble view that the HTML document can be designed in a more user friendly and visually appealing manner. Here are my two cents:

  *   On opening the documentation page, the documentation of the latest version should open with links to the documentation of the other versions on the side.
  *   Presently, to navigate from one section of the documentation to another, the user needs to go back to the Home Page and search the Table of Contents. Unless someone is reading page by page, the navigation process is a little difficult. Instead if the table of contents is always displayed to the left side of the screen (an expandable list showing the major topics and nested sub-topics) the user might be able to navigate the different parts of the document faster.
  *   The linearly organized information can be organized according to the knowledge level of the users. For example: The main page could feature a section for new comers which would have instructions for installation, very basic usage examples of the application etc. Another section might have a list of basic to intermediate level HOW-TO's - things which a user might have to setup/encounter within the first few weeks of using the software. Finally a section could be dedicated to advanced knowledge about each topic.
  *   Right now, there are 15 major sections on the main  page, each with its own sub-topics. I can't be sure but maybe such a classification of these topics will help users understand the system faster.
  *   Like Django, we can also provide a 'Get Help' box to the top right page. It can provide links to the IRC, Faq's section, mailinglists, reference document etc.

To explain the above points better, I have created a rough draft of what the main page will look like, which is attached as a pdf with this mail.
2. Adding user comments to the documentation. Postgre , PHP and a lot of other open source projects allow users to comment below the official pages detailing their own use cases, issues faced and the solutions found. This might be a good idea and will help our community grow. We can let the reader decide whether the user comments are displayed or not.
3. Creating a list of frequently asked questions for user reference. Even though we have a very detailed documentation, compiling a list of common issues, faced by the users, and their solutions might improve the user experience.
Documentation is an important part of any open source project and I believe that these simple changes might help make evergreen more inviting and convenient for beginners and intermediate people alike. However, I am just a newbie and cannot even begin to guess the other issues (if any) faced by people using the documentation. Hence, I will be very grateful if you could share your thoughts and views on the current documentation and your ideas to make it better.
Thank you.
Regards,
--
Snigdha Dagar
Electronics and Communication Engineering
IIIT Hyderabad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20140926/d46c03f2/attachment.htm>