[dev] documentation folder for applications

[Vilius ?umskas]

Gunnar Wrobel <wrobel at horde.org> ra??:

> Quoting Ralf Lang <lang at b1-systems.de>:
>
>> Am Freitag, 1. Juli 2011, 17:11:27 schrieb Jan Schneider:
>>> Zitat von Vilius ?umskas <vilius at lnk.lt>:
>>>> Hi,
>>>>
>>>> I've noticed that most released applications install their
>>>> documentation into /usr/share/pear/doc. Is there another good reason
>>>> for this except that "all PEAR packages install documentation into
>>>> pear/doc"? I can justify why this is OK for libraries, but in my
>>>> opinion INSTALL/UPGRADING documentation for applications should be
>>>> installed into application root folder. Because it is really
>>>> uncommon for the administrators to find documentation in
>>>> /usr/share/pear/doc. Especially for administrators of web
>>>> applications (even if they are distrubuted through PEAR).
>>>
>>> Good question. Policy-wise they should be using the docs role and thus
>>> being installed to PEAR's doc folder. But I could see us ignoring that
>>> and using the horde role instead, if that is consensus.
>>>
>>> Jan.
>>
>> Actually, when packaging for distribution I change the doc_dir value to the
>> system's doc path. Docs are ending up where the docs of rpm packages are
>> expected to be.
>>
>> I see it reasonable to have a pear package's docs where pear  
>> package docs are
>> expected, too.
>>
>> As I understand the horde role, it's mainly a role for web-accessible parts,
>> right?
>>
>> I see no need to have docs in a web-accessible dir (and possible reverting
>> this with a .htaccess file)
>
> Same here. Docs should be "doc" role to allow clean separation of  
> files depending on - well - their role and there is no specific  
> reasons why those should be web-accessible.
>
> The install location can of course also be tweaked during the  
> installation which we could mention in the install instructions.

I agree that there is no point to make docs web-accessible, but they  
should be easier to find. As I said, web application administrators  
are still used to search for documentation in www root. Moreover,  
currently various Horde places points to the folder which doesn't  
exist. For example:

"The test script is currently enabled. For security reasons, disable  
test scripts when you are done testing (see horde/docs/INSTALL)."

Documentation cross-links doesn't work too.

Also, currently some documentation files like README and COPYING are  
located in the application's root, but installed into "data" role for  
some reason. I suppose this is because of Chora, but maybe it makes  
sense to change Chora so it can show README from /docs/ too?

> What might be nice though would be a post installation script that  
> just spits out the directory names that received horde files. Not  
> certain though if this is easily feasible so that it always happens  
> as the last action after an installation (whether it might be a  
> single application installation of the installation of a bundle).

Could be a solution. But only if this is implemented sooner not later.  
IMHO easy documentation for open source project should be one of the  
biggest priorities, so new users can easily install/upgrade and help  
themselves. And by doing so increase user base and the amount of  
coming-in patches of course :)

Considering the above will be implemented I propose the following structure:
a) All documentation should reside in /application/docs folder in Git,  
including README and COPYING.
b) All documentation should be installed under PEAR's doc role.
c) All references in Horde interface should be updated to point to  
real folder. Probably can get it from include_path? Or maybe linked to  
the website?
?) Not sure what to do with documentation cross-links.

-- 
   Best Regards,

   Vilius