Re: [Indic-computing-devel] [RFC] indic-computing website improvements.

[<a_j...@ya...>]

> 1) From the perspective of a new volunteer for website maintanence:
>
>    The order of prerequisite reading is not specified.
>    Here is a suggested order:

[snip]

Suggestion taken.

>    It would be very helpfull to finish section "3.1, Directory
> Structure" of the documenation design goals document.

Sure.  I guess this could be added now.

> 2) Documentation layout.
> 
>    Three formats are in use, with no apparent logical distribution in
> directories. They are, sgml, html, and ettext. It would be nice to
> make a policy decision about which format to stick to ( even if it
> makes the site slightly uglier. ) Once the project has obtained
> critical-mass in terms of volunteers for site maintanence and content
> management, we could think about diversifying.

We are using different tools for different requirements. 

DocBook is being used for the 'heavy-duty' documentation that needs
"indic" stuff in it.  HTML is used only for the website.  EtText could 
be dispensed with since it is used only for a very small part of the 
website -- I had initially thought that being able to write "pseudo
plain 
text" would be of help to people willing to work on the website. 
However, there seems to be only one person working on the website 
(me :)) and I find EtText more of a hindrance than a benefit.

>   Can we cut down on the number of tools used for documentation
> maintanence ? As of now, a prospective documenter has to know 6
> tools namely: html, docbook sgml, ettext, webmake, bsd make, python.
> A shallower, smaller learning curve can bring in more volunteers at
> this stage. For now this is a substantial requirment for a casual
> contributor.

If you are writing documentation, today you need to know only
two tools, any text editor ('vi' or 'emacs' say) for editing 
and 'make' to build everything.  You don't really need to know
how the rest of the toolchain works -- the intent is that 'every
thing just works'.  For documentation, we are using one SGML "format"
namely, DocBook.  

The website could conceivably be written using DocBook too (for 
an example, see DocBook author Norman Walsh's home page).  I seriously
considered this when designing the infrastructure.  The plus point
of this approach was that we integrate our 'website' with the rest 
of the standalone documentation being written, but the drawback
was that DocBook isn't a good DTD for describing website content (IMO).

In the end I chose plain HTML for the website's content and 'WebMake'
to stich the pieces of the site's content into a coherent website.

Coming to casual contributors, these folks aren't affected by the 
internals of the toolchain (or even the specfics of HTML or DocBook) 
since they can contribute using plain-text too.

> put down the excellent work of current volunteers, but merely as a
> means to elicit discussion.

Its been a week+ of silence since your post, so I thought I'd chip in
:).


=====
Joseph Koshy, FreeBSD Developer, http://people.freebsd.org/~jkoshy/
Founder/Manager/Programmer/Peon, The Indic-Computing Project
                                 http://indic-computing.sf.net

________________________________________________________________________
Yahoo! India Matrimony: Find your partner online.
Go to http://yahoo.shaadi.com