[pmwiki-users] Re: Re: Root README.txt With a docs/ Directory

christian.ridderstrom at gmail.com christian.ridderstrom at gmail.com
Fri Dec 30 16:06:26 CST 2005


On Fri, 30 Dec 2005, H. Fox wrote:

> Out of curiosity, what's bothersome about having only a helpful README
> in the root and a few convenient, newbie-oriented docs in a non-servable
> docs/ directory?

The only drawbacks I can think of are an extra directory (which doesn't
really bother me) and the additional work of maintaining a duplicate set
of documents (in text format).

Another possible drawback is that I at least find it more convenient to 
contribute to the documentation when it is as simple as editing a wiki 
page. You have to handle a different work flow to get fixes into the text 
files.

Unless... what if we let the text files be generated from wiki pages? For 
instance, README might simply be text taken from PmWiki.README. Patrick 
could probably automate this process pretty easy, and if necessary lock 
the pages.


> Having the docs/ directory opens up the possibility of bundling more
> configuration samples and an INSTALL.txt that someone can use to get
> their wiki running -- *then* the online docs take over.

I'm not necessarily against a separate docs/, but right now I'd probably 
vote for scripts/examples/ as the place to put sample scripts. The README 
should either way of course clearly state where the examples can be found.


> > The main documentation exists in form of wiki pages within wikilib.d,
> > which the above does not make clear. So perhaps it can read:
> > wikilib.d/      Default wiki pages including main documentation
> 
> How do you read those if the wiki isn't installed?  What about someone
> who's curious, but nervous about installing?

A perhaps crazy idea could be to pass along a HTML-version of some of the
important wiki pages in wikilib.d/ and place the HTML-version there as
well.

Anyway, if I understand this correctly, the person installing this only 
has a problem if:
* He has no internet connection, and
* He has not yet installed the wiki software

In this case, you feel separate documents are needed?

(Another slightly related idea would be to make the PmWiki documentation 
available for download as HTML-pages, so that it could be downloaded 
together with the PmWiki tar file).

> The text files in docs/ shouldn't replace the main documentation,
> rather they should supplement and enhance it.  This will make PmWiki
> more attractive to people who are installing for the first time -- or
> maybe just considering doing so.


> I agree that an empty pub/css/ directory should be included in the
> distribution.

I agree as well... does anyone not agree?

/Christian

-- 
Christian Ridderström, +46-8-768 39 44               http://www.md.kth.se/~chr






More information about the pmwiki-users mailing list