[OPEN-ILS-GENERAL] ***SPAM*** Re: Evergreen Doc site Revamp

[Snigdha Dagar]

Hello Josh,

Thank you for your feedback.

Yes, I agree that the user comments would have to be moderated. Maybe this
could be done on a weekly basis. This would ensure efficiency while also
not increasing the workload too much

My idea was in fact to have an expandable table of contents, as you
suggested. It would be somewhat like what google app engine does here -
https://cloud.google.com/appengine/docs/python/gettingstartedpython27/introduction.
I understand your concern and I think the design could be adjusted in such
a way as to not waste or decrease the screen space too much.

I am sorry, I missed out on the search tab in my design. Custom search, as
you suggested, is a great feature. It would make sure that the user gets
exactly what he is searching for, and make the entire database of
documentation more accessible. This would be especially useful in the case
of irc logs and archives of the mailing list (since they aren't included in
the search right now). Since the IRC logs and the archives already have a
search option, I think this feature would not be very difficult to
incorporate.

Also, do you have any other suggestions on the documentation ( not just the
design but the content as well) ?

Regards,
Snigdha

On Fri, Sep 26, 2014 at 8:00 PM, Josh Stompro <stomproj at exchange.larl.org>
wrote:

>  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
>



-- 
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/942ac928/attachment-0001.htm>