How2PyII

[JohnMc]

How2Py, was getting a little long. The previous discussion seems to
have brought out a couple principles --

* More emphasis on content than form to get the pump primed.
* Nobody said it but I seem to sense that more people would be
comfortable with the idea that source type (pdf, rst, doc, odt) not be
an issue for submitting How2To's.

* Finally Alex F recommended that the source code be provided in
a .zip/.w2p format.

Did I miss anything? That brings up additional items, of various time
scales --

1) Where to host the submissions? Open to recommendations. Possibly
dirt simple on a temporary basis.

2) Develop a midterm goal of a submission and catalog system with
search for How2Py.

3) A little more ambitious and Alex F deserves the credit based on the
last bullet above. Provide a copy of the code with the article. Why
not turn that around a bit -- provide the code with the article
inside? Any How2Py document is an application. The article(s) would be
housed in ../static. The lead article would have an agreed to standard
name. The extension of which would be any agreed to set of file types
(eg. .doc, .rst,.odt, .htm, etc). There is a How2Py controller that
looks for that standard name, determines the extension and brings to
bear the OS or How2Py resources to read the document. The associated
code for the article is contained in a MVC layout that the author sees
fit to offer.

Couple of advantages to this. File type concerns are reduced. Code is
ready to run. Tools for making HowTo's easier to create could be
provided. Once the document is written it can utilize the Web2Py
packaging in preparation for distribution.

[Benigno]

Just to add a few comments to this, there are a few "buts" with one t,
that I see in this approach:

- It doesn't encourage writing quick articles of maybe, one paragraph
and a couple of lines of code.
- It doesn't make it easy to comment and review by other people.
- It doesn't make a quick edition of the article fast or easy, (ie
takes more work to fix something, which ussually leads to less errors
corrected or improvements made).

However, it gives you more freedom as to what tools to use to
document, and possibly better formated articles.

In this line, it reminds me of an e-zine approach that its beeing used
for example in Csounds http://www.csounds.com The ezine or journal can
be found: http://www.csounds.com/journal/articleIndex.html
Basically, they give a little structure to the different articles
received by creating Issues of the journal, whenever there is a
critical weight of articles being received. Is this closer to what you
had in mind? (adding the downloadable zip packages including
documentation?).

I know its comming again on the same subject, but if we had a wiki,
this would be a very nice complement, my problem is probably that in
my mind I am trying to cover some of the functionalities I feel
missing on this attemp to create user documentation.

Cheers,
Benigno.

[hcvst]

How about using Massimo's Killer App idea
http://groups.google.com/group/web2py/browse_thread/thread/995e36b68c0c7e51/11511528c0753952?lnk=gst&q=killer+app#11511528c0753952
to distribute these article.apps. A distributed howto/app repository
sounds fun!

HC

[JohnMc]

Benigno,

All very good points. Some possible mitigation --

- It doesn't encourage writing quick articles of maybe, one paragraph
and a couple of lines of code.

Include a built-in editor like NiceEdit? My bigger concern might be
the baggage ratio in such articles. 99% of the file being the
application for something less than a page. I will have to do some
quick tests to see how bad that would be. (Course I have seen 2mb
patch files for 8 lines of code too...:) )

- It doesn't make it easy to comment and review by other people.

I would agree with both points here but one could be mitigated. Also
one could level that observation to most other formats, like my PDF
article as well. Comments? Depending on how sophisticated you wanted
to be I could see two approaches. 1) Direct mail to author. Built-in
submission form in How2Py controller sent via xmlrpc to a mail
forwarding application. The fa decodes who should receive the query
and sends it. 2) If we did have a wiki why not have the wiki support
an xmlrpc to receive comments that would be added to the comments page
of that article/app?

- It doesn't make a quick edition of the article fast or easy, (ie
takes more work to fix something, which ussually leads to less errors
corrected or improvements made).

My reply would be a variation of the above. If one has NiceEdit
available one has the editor to create/edit the article. The only
additional burden is requiring the author to 'mount' the app/article.
That's tap, tap, tap, click.

But I will concede that it is more effort than say a wiki page edit.

I am probably getting a bit ahead of myself as there are other issues
of a simpler nature that need to be conquered.

JohnMc