for your info
mdipierro
Beerc
I ***LOVE*** the tight integration of web2py components.
I ***LOVE*** the compactness of web2py.
I ***HATE*** over-abstracted, over-engineered, over-complicated, Java-
style enterprisey code. YAGNI, KISS, "less is more" are hard-earned
parts of developer wisdom. Most of the web frameworks somehow derailed
their trains from the lean track. Most of them follow a wrong set of
_dogmas_.
Weheh said: "Web2py is wonderful because of its simplicity,
consistency and performance."
YES, and of its security, and of its backward compatibility, and...
and... and...
</subjective part>
<objective part>
Selecting developer toolset is a matter of taste. Obviously. Always.
If you abominate from web2py, don't use it.
</objective part>
<!!!!!!!!!!>
Web2py has a single, but big weak point: scattered, hard-to-follow
documentation. The importance of up-to-date, detailed, clear
documentation is undeniable. Undocumented features are similar to
untested code. Out-of-date docs are similar to buggy code.
Most programmers hate writing documents. But writing docs is *easy*:
* It is error prone? Errors are fixable, docs are never perfect!
* It is time consuming? Write some *short* sentences after succesful
coding! Be proud, praise your work!
* It is difficult to write in clear, concise, elegant style? Then
write some foggy, verbose, clumsy fragment. Somebody, some time will
make it clear, concise, elegant.
Good documentation has two mains parts:
* A wiki to keep the front. With *all* of the usable informations,
details and fragments. [MISSING BADLY].
* A book for beginners, to ease the start, to stimulate the appetite.
[CHECK]. Toss details into the wiki, reference them in the book. [THIS
IS A TRICK, NOT A REQUIREMENT].
</!!!!!!!!!!>
Jonathan Lundell
> I ***LOVE*** the tight integration of web2py components.
>
> I ***LOVE*** the compactness of web2py.
These are by far the two biggest reasons I started using web2py, mainly over Django and its kin.
Now that I have a little more experience, I'd add this mailing list to my list of reasons.
My biggest complaint is what has been referred to as "magic" behavior, and in particular the relative opaqueness of some of that magic. Documentation could help there by making more clear what's going on inside; there's a little too much "do this and it just works" right now. But that's true of (say) RoR, too, so web2py isn't alone.
I like the idea of a wiki that parallels the structure of the book. I'd also like to see a page each for all (or at least the important) classes, linked to their mentions in the mainline docs, where among other things magic behavior is explained.
mdipierro
possible with a disclaimer about "do not reproduce in print". The main
issue is that the book is in latex and not easy to convert.
DenesL
On Feb 8, 11:33 am, mdipierro <mdipie...@cs.depaul.edu> wrote:
> I am considering posting most of the book on line in HTML. This may be
> possible with a disclaimer about "do not reproduce in print". The main
> issue is that the book is in latex and not easy to convert.
mdipierro
Moreover they are not reversible so changes in the wiki would not
easily propagate into the latex book (which I consider the master
documentation).
Jonathan Lundell
I investigated that a couple of years ago for an online journal. There are tools, but (at least at the time) they were not very good, and not maintained. So we gave up and stuck with pdf.
How about a restricted-use PDF?
pistacchio
decide where to host this new documentation (http://wiki.web2py.com/
may be the most obvious bet). set up a page of links that reproduces
the tree structure of the pdf summary. then one by one, anyone can
copy / past text from the pdf to the new pages and format it.
this is the most straight forward way to get it done, i think, and it
leaves plenty of space for people to correct / add / update infos on
all the topics.
pihentagy
I like especially the side notes...
The author would review each comment and decide what to do, so IMHO no
need for an automatic hypothetic html2latex tool...
Thadeus Burgess
Take a look at http://www.cubicweb.org/doc/en/index.html
That is nice, its in a tutorial style format, but it is a wiki so it
supports contextual searching via google.
Its not all that special just a basic wiki where the pages are linked
together in order.
-Thadeus
> --
> You received this message because you are subscribed to the Google Groups "web2py-users" group.
> To post to this group, send email to web...@googlegroups.com.
> To unsubscribe from this group, send email to web2py+un...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
>
>
Thadeus Burgess
knowledgeable enough in web2py to write documentation. The ones who
are knowledgeable enough in web2py are too busy (either with web2py or
real world) to write documentation.
I cannot stress enough the fact that any and all contributors
(including Massimo) needs to start documenting as you go, put it in
the source code, put it on the wiki.
As long as the information is there then english majors can come along
and format the docs correctly and in a logical manner.
We need to write documentation on how we are going to document web2py!!!!
A page needs to be added to the wiki, that will be a complete
structured document of how web2py will be documented, including coding
style, doctest style, and wikidoc style.
We don't need a non-web2py based system, we have web2py wiki system
that can do all that we need, we just need to use it.
-Thadeus
Jonathan Lundell
> the problem with pdf is it is not searchable.
>
> Take a look at http://www.cubicweb.org/doc/en/index.html
>
> That is nice, its in a tutorial style format, but it is a wiki so it
> supports contextual searching via google.
>
> Its not all that special just a basic wiki where the pages are linked
> together in order.
I'm not arguing for pdf (though of course it *can* be searchable); only that it's a better match for latex than html is.
I do like having printable docs.
Djangobook is nice.
A problem with wiki.web2py is that the underlying wiki is limited, so it's relatively hard to edit, and the appearance of the output leaves a lot to be desired. (And no, I don't have time to work on it, though if web2py had a first-class wiki, I'd seriously consider using for my CMS needs.)
Thadeus Burgess
check). I just need somebody to tell me where to put it.
-Thadeus
Richard
> I am considering posting most of the book on line in HTML. This may be
> possible with a disclaimer about "do not reproduce in print". The main
> issue is that the book is in latex and not easy to convert.
this is fantastic news!!
On Feb 9, 4:01 am, mdipierro <mdipie...@cs.depaul.edu> wrote:
> Lookin into that but I am not sure they work as good as they should.
> Moreover they are not reversible so changes in the wiki would not
> easily propagate into the latex book (which I consider the master
> documentation).
An automated solution sounds difficult and time consuming. If you
permitted, I could manually copy the PDF into a wiki or some other
app. And I'm sure others would be willing to help too.
Beerc
medium to large:
---------- Autoconversion:
It is very hard to *automatically* convert any bigger, heterogenous
material to a *good* wiki format. Attemptions are plenty, all of them
failed. Probably it is impossible. Except conversions from other wikis
(e.g. from MediaWiki to DokuWiki or vice versa). Causes are many. Lots
of.
(Opposite ends: manual conversion, small material, homogenous
material, poor quality wiki.)
It is very hard to *automatically* convert any wiki to a *good* book
format. Probably impossible.
(Opposite ends: manual conversion, poor quality book.)
I suggest abdicating the hope for autoconversions. Superfluous work.
---------- Why HTML?
Main argument for an *HTML documentation*: anybody can link into one
of its pages. This seemingly simple feature brings huge benefits over
the time.
Internal and external linking and link handling capabilities in PDF
and other formats are very limited. Hypertext offers huge inherent
benefits, but document formats (PDF, CHM, DOC, RTF etc.) are
essentially sequential.
Sequential structure of conventional documents helps *learning* and
storytelling. Structure of heavily linked hypertexts helps *writing*
(for example thru ad-hoc linking of new subpages) and similarity based
searching (thru "surfing"). It follows that conventional documents
helps beginners, hypertexts helps to write and read complete
documentations.
---------- Why wiki?
Main arguments for a *wiki* (online, editable HTML documentation):
* Simple syntax, so anybody can contribute. (Better, if only
registered users can.)
* Unlimited page revisions. So you can compare them. Easy to find the
modifications with colored, side by side diff (built in feature in
better wikis).
* List of recent changes. So easy to find the new parts.
* Section editing helps quick changes.
* Easy to embed images in many formats and arbitrary sizes.
* Page locking or conflict resolution precludes edit conflicts.
---------- Which wiki?
Web2py has a wiki, with unique, powerful features: T3 (e.g.
wiki.web2py.com). While I'm delighted with T3, and I hope its wiki
capabilities will improve over the time, *now* and in the near future
it isn't appropriate for carrying a *complete* documentation of a
serious software project.
There are lots of wiki. There are only a few good ones. While it can
be hotly debated, I'm sure DokuWiki is the best choice for documenting
web2py. Because:
* All data is stored in plain text files. So we can versioning them,
parallelly with other parts of the project. And it is easy to generate
wiki pages.
* DokuWiki is easy to use, feature rich and standards-compliant.
* If a project using Trac, then probably it is better choice than
DokuWiki. (Trac uses plain text files, easy to use, moderately feature
rich.) But web2py project don't using Trac.
* If a project similar to Wikipedia, then probably it is better choice
than DokuWiki. But web2py:
** less popular than Wikipedia (yet ;), so don't require eminent
scalability of internal search,
** and don't require advanced media handling (media revisions etc.).
(Scalability of search function in non-public, large dokuwikis is
problematic. In public dokuwikis web search engines can substitute
internal search.)
Yes, DokuWiki is PHP-based. So we will lose the purity. Bearable pain.
---------- How to wiki?
This deserves longer explanation.
Anand Vaidya
etc). My understanding is that,
=> The core documentation must be maintained by core-devs who know the
code inside out, This doc is the ultimate reference and should be in
Restructured format text-files, in a SVN/Hg repository.
RST to HTML conversion should be performed and published online. Users
should be able to submit comments (Django allows at the paragraph
level, pylons allows comments at the page level). These comments
should be reviewed the core-dev or core-doc team and the docs updated
frequently.
=> User generated docs which are likely to contain errors ,
inaccuracies, tips, hints etc should be maintained in a separate wiki/
site such as moinmoin or a CMS such as Drupal or Joomla. Some
extremely useful tips etc can be pulled into the core-docs. Some can
be left in this state and maintained separately.
I am accumulating all my comments here: http://webtopy.org/community/w2py-doc-conundrum
I am willing to assist in a one time Latex or PDF to ReST manual
conversion . A group of members on this list can form a taskforce and
splitup chapters and perform the conversion.
If one of the list members can come up with a budget and a deadline to
develop a kickass web2py wiki, we can come up with contributions /
funds. I am willing to put up USD 100
mdipierro
1) convert the book to markdown (including conversion of eps images to
png and conversion of references)
2) real time markdown to html (using special markup for references)
3) ability to annotate the book sections with user comments
4) automatically link all keywords in code example with corresponding
docstrings
5) everything will have versioning so periodically I can diff the book
and the docstrings and generate a patch (this will not be fully
automated because the patch will be for wiki syntax not latex but I
can convert back).
When done I will loose some money from book sales so I will start
taking donations. ;-)
*** If you want to help, help make the Sphinx documentation work!!!
***
So we can replace epydoc with Sphinx.
Massimo
Jonathan Lundell
> Some experiences from many years of working with wikis, small to
> medium to large:
This all sounds very sensible.
We ought to take advantage of homogeneous material where we can find it. Docstrings in particular could feed a set of wiki pages (read-only, unless someone wants to take on the back-edit problem).
On the choice of wiki, I'd take a look at MoinMoin (with the caveat that I have all of about 20 minutes experience looking at it). It seems relatively mature, uses plain-text files, uses a MediaWiki-flavor markup, and is written in Python to boot. (I agree that this isn't a major point, but it's at least a plus, in that it's the home team, and as a group we have the resources to contribute there if we really need a feature or a fix. And if it's really good, I'd consider it as an adjunct to a web2py website of my own.)
Jonathan Lundell
> *** If you want to help, help make the Sphinx documentation work!!!
> ***
>
> So we can replace epydoc with Sphinx.
What would this entail? I'm guessing that most of us don't have a clue about Sphinx.
Beerc
I admit my experiences with MoinMoin are old (around 2005).
Then it was mediocre.
After your current recommendation I revised my memories.
Latest versions are far better than the older ones.
* It still hasn't section editing. Seemingly minor feature, but
*crucial*.
* The size of editing textarea is fixed. In DokuWiki you can resize
it, size data stored in cookie. Valuable feature (not crucial).
* Otherwise now it seems very good.
Despite its deficiencies, I'm not opposing MoinMoin.
Cut and paste+desktop editor+cut and paste is an affordable substitute
for section editing.
Jonathan Lundell
>> On the choice of wiki, I'd take a look at MoinMoin
>
> I admit my experiences with MoinMoin are old (around 2005).
> Then it was mediocre.
>
> After your current recommendation I revised my memories.
> Latest versions are far better than the older ones.
> * It still hasn't section editing. Seemingly minor feature, but
> *crucial*.
I agree.
> * The size of editing textarea is fixed. In DokuWiki you can resize
> it, size data stored in cookie. Valuable feature (not crucial).
Nice, though (for me) not an issue, because Safari resizes textareas. Also, the default MM edit textarea is pretty big, fwiw.
> * Otherwise now it seems very good.
>
> Despite its deficiencies, I'm not opposing MoinMoin.
> Cut and paste+desktop editor+cut and paste is an affordable substitute
> for section editing.
Painful, though.
Richard
Anand Vaidya
RST without any additional software (only python-docutils needed) and
with markdown too (needs python-markdown installed).
Moreover, with a theme such as Moniker, the wiki looks neat.
Regards
Anand