Re: SilvaFind - a README.txt please

Marc Petitmermet wrote:
> dear developers
> 
> i don't want to offend anybody here; just allow me to give some  
> comments about SilvaFind and my usual nitpickings;-)
> 
> could anybody please write a README.txt for this product? i know that  
> it's not officially released yet but i just did a few tests and i'm  
> almost clueless here. there is a nice form in the edit view but the  
> public view shows "publication time : ('', '');" and a list of links  
> which are from a complete different domain...
> 
> ahhh, i need to check those boxes to enable the form. what about some  
> notes here (most silva products have notes but not SilvaFind)? or  just 
> add a column heading "enable" above the checkboxes? and when  nothing is 
> enabled the public view should not show anything.
> 
> i still don't know why it shows any results when nothing is searched  
> for and why it shows results from complete different domains (virtual  
> host problem?).
> 
> the "from" and "to" fields are not fool proofed. i can get nasty zope  
> errors: DateError, SyntaxError, Unable to parse. the user really does  
> not know what syntax is expected.
> 
> nitpicking 1: there are mixed upper lower cases: "Full", "From", "To"  
> but everything else starts with a lower case.
> 
> nitpicking 2: can you have a look at the rendered xhtml code. is it  
> intended that some fields have a class, some not; some have an id,  some 
> not; some have a type, some not? i noticed this because the from/ to 
> fields are rendered differently than the other fields in our setup  
> (borders).
> 
> nitpicking 3: empty span tags. let me cite kit here, if you allow;-)
> https://infrae.com/issue/silva/msg7525
> 
> nitpicking 4: there is an "is" missing in the sentence bellow. my old  
> brain expects a "from" after the "or" and then the sentence doesn't  
> make any sense. but i guess that this is only my problem not being a  
> native english speaking person;-)
> 
> "This a special document that can show a list of content items  
> resulting from a search with specific values for criteria or a form  to 
> enter search criteria before getting results."
> 
> regards,
> marc
> 

Hi,


I would like to support Marc at this place. And I think as the people 
who found even extra budgets for giving Infrae financial support in the 
area around this product the least thing to request is some 
documentation coming with the software.

A software product without an at least minimal documentation/readme is a 
piece of software with a major bug - even if it's fun for the developer. 
It's not only about neglecting other people who are supposed to use this 
software, but it's about forcing them to use time for senseless 
experiments, time which could have been invested better to find, for 
example, real bugs in the software and make it better for all.

*****************************************************
Documentation can and should be delivered already in a first iteration, 
and then extended and detailed within each following iteration.
This is part of the quality standards of software supposed to be used in 
a productive way by others than only the developer himself.
*****************************************************

Really, there is no necessity to not deliver some instructions with any 
piece of software which is supposed to be used by others. ETH has 
financed so much of Infrae's software, and we always have put emphasis 
on writing documentation in parallel with writing code that a complaint 
like Marc's should not be able to come up. It's just like writing unit 
tests in parallel with the code from the first iteration on. And 
unfortunately Marc is not the first from whom I hear this critics.

I am sorry, Marc, that you have to re-find how to use SilvaFind.


Greetings,
Reinhard

-- 
Reinhard Hess
Email: [email protected]
Phone: +41-(0)44-632 30 86
Fax:   +41-(0)44-632 13 12
ETH Zuerich
Informatikdienste Technologie- und Informationsmanagement
WEP J17
Weinbergstrasse 109
CH-8092 Zuerich