RE: [ jEdit-users ] FAQ?

[John G. <jge...@ny...>]

> On Sunday 23 September 2001 16:07, John Gellene wrote:
>
> > (1) A constrained content model:  I have looked at the Python FAQ and I
> > don't see a list of up to 100 or more questions in a single
> category to be
> > a useful presentation, even with an index.  There should be a small
> > organizatonal hierarchy; two levels seems right to me. I gather
> from your
> > response that the out of the box, the Python FAQ package has no
> flexibility
> > in that regard.
>
> I agree with this, If you really want to get such a hierarchical
> model, you
> may be better of with something else, the hacking then is lot
> more than just
> changing the format somehow.
>
> > (2) Combining data collection with data presentation:  this is
> a FAQ, not a
> > bulletin board (although as others have mentioned, a PHP-driven bulletin
> > board facility like PostNuke could be very useful).  Getting suggestions
> > from users and developers is a way to put the FAQ together
> quickly, not a
> > way to maintain it.
>
> I think we have the central discussion point. I don't think we
> have agreed in
> this, Some people think it's a good idea that anybody can post
> questions an
> answer, with maybe somebody postediting them, I even see that it
> is going to
> be very slow to collect questions and aswers if they have to be sent by
> e-mail to the list, the discussed and finally aproved. Of course
> we can agree
> in a model, where something is discussed and you take care of editing,
> writing and formating, is not my ideal approach but it has its
> good points
> (at least it will look uniform).
>
> We should probably agree on this before deciding which tools to
> use. If we
> decide to have you a solely editor, then you have to choose the
> best tools
> for yourself, but a community owned FAQ should have simpler and widely
> available tools
>
> >
> > (3) Combining data serialization with data presentation:  HTML
> is not the
> > best way to maintain the content. I use SGML because the tools
> are easier
> > and faster to use than open source XML  tools, but the SGML becomes XML
> > with a header tag and a DTD reference.  All of jEdit's
> documentation is now
> > maintained in DocBook XML, which comes very close to a pure
> content model,
> > and I think the FAQ should be maintained primarily in that form as well.
> > Maintaining two HTML versions does not make sense to me.
>
> In this case is data is stored in raw files (pure content model),
> so out of
> that you can generate sgml or html, using some basic rules. If you want
> the source to be in sgml in practice you will ban anybody who doesn't
> know/like SGML. Again I return to my previous point, do we want a
> community
> owned FAQ or a centralised edited one?
>
> > (4) Editing concerns:  I'm really not interested in editing submissions
> > from my fellow developers in a fish bowl.  I don't know who
> would be, and I
> > don't think we would get as many submissions in that
> circumstance.  Maybe
> > the same number of questions, but fewer answers.  As matters stand now,
> > since I requested submissions I have received only one
> question-and-answer
> > set and four other suggested questions, including "What's
> planned for jEdit
> > 4.0?"
>
> Right, I think we should start with some small amount of
> questions/answers and then new ones will popup naturally
>
> > One answer to this might be that there would be more submissions if they
> > could be prepared online instead of using a BeanShell macro
> within jEdit.
> > Perhaps that's true, perhaps not, but all that is required in
> that case is
> > a HTML form that emails the results to an editor and whomever
> else should
> > get them.  The rest of the package may produce some kind of dynamic,
> > real-time document quicker, but not a document up to the substantive
> > standards of the rest of the jEdit documentation.  If major hacking is
> > necessary to make the Python package do what is required, I'm
> don't think
> > it's worth the effort.
> >
> > John
>

I'm not trying to decide what anyone wants by way of a jEdit FAQ.  I'm
trying to clarify what I am comfortable doing, partly for technical reason
but also arising out of two personal concerns: first, that my time on a new
project is spent efficiently; second, the same concern for quality and
consistency that I tried to put into more than half of jEdit's current
documentation.  To me, the product you are describing, stripped of
"community" rhetoric, seems more like a bulletin board than a FAQ. I don't
oppose the project you want to undertake in the least; it's just not what I
have been talking about.

If you do want to proceed, and Slava and Mike agree to put your script on
the jEdit site, you should work out the details, get it started and consider
my 14 questions and answers as an initial contribution.  It looks like you
could also do it using your own bandwidth; obviously that's your decision.
When you're ready, I will be glad to forward the handful of emails I
received with suggestions for questions, along with the one contribution
that actually contained an answer.  If your proposal succeeds, neither I nor
anyone else will have reason to continue drafting a conventional FAQ
document.

John