maria-developers team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxx>]

On Wed, 07 Jul 2010 13:08:46 +0300
Timour Katchaounov <timour@xxxxxxxxxxxx> wrote:

Timour> Danny,
Timour> 
Timour> this the log from a short discussion about how to provide the
Timour> documentation for Sphinx to our users. Can you think of some
Timour> easy way to automate at least the notification process that
Timour> the docs changed?
Timour> 
Timour> <timour> knielsen, shodan IMHO it wuold be best if Sphinx could
Timour> notify us automatically about changes in the docs, rather than
Timour> having a possibly outdated documentation, with a link to the
Timour> up-to-date docs. 
Timour> <timour> If we take this manual approach to
Timour> copy/paste docs for a dozen storage engines, we will end up in
Timour> a big mess. 
Timour> <shodan> timour: would
Timour> http://code.google.com/feeds/p/sphinxsearch/svnchanges/basic do
Timour> for notifications? 
Timour> <timour> shodan, isn't that a feed with all changes? 
Timour> <shodan> timour: yes, and so doc/ changes are there too 
Timour> <timour> knielsen, perhaps we could pull the docs
Timour> automatically? 
Timour> <shodan> timour: maybe we could setup a special hook on commits
Timour> to just doc/ but def not to a specific section 
Timour> <timour> shodan, I think we have to ask our docs guy what is
Timour> the best way to at least be automatically notified of doc
Timour> changes (for the same release).
Timour> <timour> To me there are 2 kinds of doc changes: 
Timour> <timour> - improvements of the docs for the same version of the
Timour> code, 
Timour> <timour> - changes due to a new release. 
Timour> <timour> The latter will be straightforward, because we will
Timour> know when we release a new version of Sphinx, but not the
Timour> former.
Timour> 
Timour> What do you think about the problem with outdated docs of
Timour> storage engines?

Well, the best way is to get the storage engine developers to update
their section of the wiki/knowledgebase whenever it needs updating.
I know some devs will be willing do this, but others will not,
especially when they have their own documentation procedures in place
(like Sphinx does).

The next best thing would be to have a notification sent to
maria-docs@xxxxxxxxxxxxxxxxxxx whenever there are changes to their
internal documentation (i.e. the doc/ dir for sphinx), or to the
documentation on their site.

For Sphinx, Google Code does allow me to have an rss feed that only
includes changes to the doc directory:

http://code.google.com/feeds/p/sphinxsearch/svnchanges/basic?path=/trunk/doc/

Any changes to stuff under /trunk/doc/ will appear in this feed.

As an experiment, I imported the feed into feedburner and then used
feedburner's "email subscriptions" feature to setup email delivery of
new items in the rss feed to the maria-docs@ list. If this works like I
think it will this will be a good way to be notified of updates to
their docs.

What do you think?

-- 
Daniel Bartholomew
Monty Program - http://askmonty.org