[OPEN-ILS-GENERAL] Evergreen Doc site Revamp

[Snigdha Dagar]

 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/07682c26/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Evergreen.pdf
Type: application/pdf
Size: 31232 bytes
Desc: not available
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20140926/07682c26/attachment-0001.pdf>