turning user group discussions into something more permanent

[Peter Krautzberger]

Hi everybody,

I've been thinking a bit about how we could turn user group discussions that produce practical solutions into something more stable and reliable that people can browse and reference more easily (and might even sometimes help improve the documentation).

The google groups aren't really designed for this. Making the information easier to find and would enable everybody (not just team members) to help other (especially new) community members by referencing reliable solutions to regularly occurring questions.

Personally, I have a long list of discussions I've filed away in a folder to be turned into FAQs or documentation "when I find the time" (which I never seem to find...).

Some examples/aspects of this.

* Forum guidelines

We don't have a good set of rules for users to prepare their messages. For example, we often reply by "link to a minimal example, what browser, what OS, link to a page" -- ad nauseam.

It seems to me that we're not doing our job as a community if we have to keep doing that. (So this email is, in a way, collecting potential topics for such guidelines.) (This is also connected to what the contact page on mathjax.org says.)

* Collecting code snippets 

A lot discussions end with snippets which could be reused if we had a place for them. Not all of them make sense to be abstracted into full examples or documentation, but all of them have some value and we would benefit from organizing (and referencing!) the code snippets outside the user group.

The natural place to put all our snippets for future reference might be https://gist.github.com/ but I have little experience with it and can't tell if it fits the bill -- maybe somebody else does?

Then again, we often use jsfiddle to investigate problems with specific content or javascript interaction and it seems the most flexible platform for minimal examples.  I'm not sure how jsfiddle could be used more efficiently -- does anyone have experience with that?

Generally speaking, important and frequent examples could eventually make it into the test folder in the main repository -- and then they definitely deserve some documentation, (both in the code and about the code in the docs). But if we get them out of the individual emails, that would be step forward.

* bug reports

Bug reports should really go to the issue tracker on github but of course sometimes it's not clear that we're dealing with a bug. To be honest, I'm not sure what could be improved.

When people think they're reporting a bug, we should send them over to the tracker, but should we send them over more aggressively, maybe even if we secretly suspect it isn't a bug? (People do search the bug tracker.)

* double posts on other platforms

I see more questions showing up on StackOverflow these days. I think that's a great idea for questions that fit on SO. The SE platform is very well designed to identify helpful answers and rank questions of importance --  and the community is more diverse.

What's a bit annoying is that we also have to deal with double posts -- which could be avoided if people were aware that a lot of regular users here are also checking SO systematically (and other platforms). Maybe we should be more active about pushing people to other platforms that we cover? 

(Btw, there was a discussion on TeX.SE a while back and agreement was that MathJax questions should be on SO, and only move to TeX.SE if they really are TeX questions, not "TeX syntax as emulated by MathJax" questions).

I'm sure I've forgotten approximately a gazillion things but this has gotten too long already. 

Please storm your brains if you would.

Peter.

[J.R.St...@physics.org]

On Wednesday, November 21, 2012 5:39:23 PM UTC, Peter Krautzberger wrote:

 

I've been thinking a bit about how we could turn user group discussions that produce practical solutions into something more stable and reliable that people can browse and reference more easily (and might even sometimes help improve the documentation).

The google groups aren't really designed for this. Making the information easier to find and would enable everybody (not just team members) to help other (especially new) community members by referencing reliable solutions to regularly occurring questions.

Personally, I have a long list of discussions I've filed away in a folder to be turned into FAQs or documentation "when I find the time" (which I never seem to find...).

Some examples/aspects of this.

* Forum guidelines

We don't have a good set of rules for users to prepare their messages. For example, we often reply by "link to a minimal example, what browser, what OS, link to a page" -- ad nauseam.

There could be a questionnaire for that at MathJax.org. Instructions : fill in the form, then copy'n'paste into a Group draft article.  Trivial to write the HTML, but be sure that all <input type=text> are sized big enough

There should be a small FAQ, pinned or posted sufficiently often, in this newsgroup itself, dealing with the use of the group and where a few other resources can be found (one of those would be a larger list of resources).  That FAQ itself should NOT deal with the use of MathJax, but it would point to the MathJax site itself and to any FAQ-like parts of that site. That FAQ should include a list of names and primary specialisms of the chief MathJax personalities in the Group - they know themselves, but incomers do not. PARTS of Usenet newsgroup FAQs can be trawled for ideas.

It seems to me that we're not doing our job as a community if we have to keep doing that. (So this email is, in a way, collecting potential topics for such guidelines.) (This is also connected to what the contact page on mathjax.org says.)

That "this" is not an E-mail; it is a Google Groups posting.  That page includes "send an email to the MathJax User Group" : "email" is wrong; it is a message.  Alternatively, "post an article [in|to] the ...".

 

The natural place to put all our snippets for future reference might be https://gist.github.com/ but I have little experience with it and can't tell if it fits the bill -- maybe somebody else does?

Do not assume that users know how to use such systems.  Better, I think, to use the MathJax site, where MathJax experts can enforce simplicity. 
 

Then again, we often use jsfiddle to investigate problems with specific content or javascript interaction and it seems the most flexible platform for minimal examples.  I'm not sure how jsfiddle could be used more efficiently -- does anyone have experience with that?

It is far too complex to solve an ordinary potential user's first problem; it will almost always be easier overall to solve it another way.   Without having solved a user's first problem, his next problem will in effect be his first.  Now recurse.

 

Generally speaking, important and frequent examples could eventually make it into the test folder in the main repository -- and then they definitely deserve some documentation, (both in the code and about the code in the docs). But if we get them out of the individual emails, that would be step forward.

* bug reports

Bug reports should really go to the issue tracker on github but of course sometimes it's not clear that we're dealing with a bug. To be honest, I'm not sure what could be improved.

If a bug is discussed here to the extent that it is understood and reproducible by a member of the "MathJax Team", then that member, who presumably will know how, should post it to an issue tracker.  The actual original bug finder may well lack the incentive - he may have got a work-round already.

 

When people think they're reporting a bug, we should send them over to the tracker, but should we send them over more aggressively, maybe even if we secretly suspect it isn't a bug? (People do search the bug tracker.)

* double posts on other platforms

I see more questions showing up on StackOverflow these days. I think that's a great idea for questions that fit on SO. The SE platform is very well designed to identify helpful answers and rank questions of importance --  and the community is more diverse.

Such things need a degree of explanation if mentioned.  They also need evaluating for accessibility in all senses.  StackOverflow is immediately unfriendly to me, because it is antagonistic to Firefox Zoom Text Only, which I always use.

 

What's a bit annoying is that we also have to deal with double posts -- which could be avoided if people were aware that a lot of regular users here are also checking SO systematically (and other platforms). Maybe we should be more active about pushing people to other platforms that we cover? 

Users have different needs and preferences : push them, and they will just go away.  But list in the Group FAQ the other platforms that "we" cover, and state that multiple posting is very unwelcome and if done must be identified as such.  But allow for those who post in place A without immediare success, and then discover Place B.

It can be somewhat unfriendly to use "we" as above when many readers will not know who "we" are; consider using "the MathJax Support Team" (or similar) on the first and some subsequent occasions.

 

(Btw, there was a discussion on TeX.SE a while back and agreement was that MathJax questions should be on SO, and only move to TeX.SE if they really are TeX questions, not "TeX syntax as emulated by MathJax" questions).

Jargon.
 

I'm sure I've forgotten approximately a gazillion things but this has gotten too long already. 

Write in international English, avoiding loose terms common in limited regions.  Above, "a lot of" would be better and shorter than "gazillion"; and "many" is better still.

At the moment, from here, http://www.mathjax.org/ seems dead; so I cannot check.  How user-friendly is it for those who cannot fluently write English?  MathJax seems to have several American experts; statistically, at least one should be able to read Hispanic.  Include an expert from the western half of the European mainland, and you'll probably get at least two other readable languages.  Then you can say, for example, "Questions in French and German will be understood, but may be answered in English".

<http://www.onemathematicalcat.org/MathJaxDocumentation/TeXSyntax.htm> includes, at the top, a tester; but the whole page is very slow to start.  I suggest including (if not already done) a similar tester on a web page of its own, with just a little supporting material.  That page is so big that I had trouble in making a copy without the main Table; but I succeeded, and now have a quick-loading local tester in under 250 lines / 7 kB.

[J.R.St...@physics.org]

On Thursday, November 22, 2012 12:57:31 PM UTC, j.r.st...@physics.org wrote:

<http://www.onemathematicalcat.org/MathJaxDocumentation/TeXSyntax.htm> includes, at the top, a tester; but the whole page is very slow to start.  I suggest including (if not already done) a similar tester on a web page of its own, with just a little supporting material.  That page is so big that I had trouble in making a copy without the main Table; but I succeeded, and now have a quick-loading local tester in under 250 lines / 7 kB.

On a temporary basis only, that tester is at <http://www.merlyn.demon.co.uk/$fish.htm>.  Readers, including MathJax.org, feel free to take a copy, personalise it to yourself, and publish it elsewhere; but not to republish it just as it is.

-- 
  (c) John Stockton, near London, UK.  Using Google, no spell-check.
 Mail: J.R.""""""""@physics.org or (better) via Home Page at
 Web:  <http://www.merlyn.demon.co.uk/> (may move soon)
 FAQish topics, acronyms, links, etc.; Date, Lagrange, JavaScript, ..|

[Peter Krautzberger]

Thanks for sharing your perspective.

Looking forward to reading other people's ideas.

Peter.

[Marc Grober]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

sounds like much of the discussion had at moodle.org, with the result
that not much happens: the forums are a mess (that is what forums
are), the docs arde not well maintained( at least my theory being that
any issue resolved in a forum needs to be adequately then documented
in the docs), and the tools for pointing queries to the best doc
solutions never implemented though virtually delivered prete a porter.

However, the idea of a set of wiki documentation open to editing by
the community is great, and a device to point queries to the most
likely solution as the docs grow will help avoid needless thrashing in
the list.

> what the contact page on mathjax.org <http://mathjax.org> says.)

>
>
> That "this" is not an E-mail; it is a Google Groups posting. That
> page includes "send an email to the MathJax User Group" : "email"
> is wrong; it is a message. Alternatively, "post an article [in|to]
> the ...".
>
>
> The natural place to put all our snippets for future reference
> might be https://gist.github.com/ but I have little experience with
> it and can't tell if it fits the bill -- maybe somebody else does?
>
>
> Do not assume that users know how to use such systems. Better, I
> think, to use the MathJax site, where MathJax experts can enforce
> simplicity.
>
>

> Then again, we often use jsfiddle <http://jsfiddle.net/> to

-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.16 (Darwin)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iQEcBAEBAgAGBQJQroPaAAoJEMCi9wxDaNqEZq4IANKKrSOq6MJa0dj1evNuOSwC
7ScCGWwhq4s20LnXX8UO1JyrkHTdUxp8Bx7Ww+vH/leyMRAJBvNCqfAlmwWt6Yi/
QPaHo2/6sv+hJK36HvgduS2eb6U/XsqEn/XtF85jZEE4AC0KUxUKUkHfhxfcfhXA
rqUDrJIBp5OV+t/dP+8kbILZF3DGX+lJ6EcSiEZLyniQJacs//Eyq6UrcyZ/sBc7
xAp2n/cMOyBF45qTumYbL/s4kF9WgdbVTaRoWvmOeHyQFAl0IBfWZgEN54UCgWdJ
xfF2arGjJqEO42KLF+K7zBVCjDG0kWV0JUVf9b461T2YQygqwFYO2/fLpk+QPGk=
=OQZr
-----END PGP SIGNATURE-----

[Peter Krautzberger]

Thanks, Marc, that's very helpful.

[J.R.St...@physics.org]

On Thursday, November 22, 2012 12:57:31 PM UTC, j.r.st...@physics.org wrote:

On a temporary basis only, that tester is at <http://www.merlyn.demon.co.uk/$fish.htm>.  Readers, including MathJax.org, feel free to take a copy, personalise it to yourself, and publish it elsewhere; but not to republish it just as it is.

As now uploaded, it will work only in November.  That protection of my bandwidth can easily be removed from any copy.  JRS.

 

[Davide P.Cervone]

* Forum guidelines

We don't have a good set of rules for users to prepare their messages. For example, we often reply by "link to a minimal example, what browser, what OS, link to a page" -- ad nauseam.

It seems to me that we're not doing our job as a community if we have to keep doing that. (So this email is, in a way, collecting potential topics for such guidelines.) (This is also connected to what the contact page on mathjax.org says.)

Here is a page I've always liked that gives good advice about making bug reports in general

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

It is too long, but could be a reference.

* Collecting code snippets 

A lot discussions end with snippets which could be reused if we had a place for them. Not all of them make sense to be abstracted into full examples or documentation, but all of them have some value and we would benefit from organizing (and referencing!) the code snippets outside the user group.

The natural place to put all our snippets for future reference might be https://gist.github.com/ but I have little experience with it and can't tell if it fits the bill -- maybe somebody else does?

I haven't used it myself, but have seen it used.  Some pros and cons:

Pros:

  - It handles the code well

  - It has ability to do discussions tied to the code

  - It is forkable and maintains history

Cons:

  - It doesn't seem to have a way to tie the content to a specific project (so no automatic way to list MathJax Gists or link back to MathJax)

  - The format is fixed, so you can't put discussion or description above the code, for example, though you could add discussion below it.

  - It may be harder to arrange for a consistent presentation of information about the examples (this would have to be done in the discussion section).

Then again, we often use jsfiddle to investigate problems with specific content or javascript interaction and it seems the most flexible platform for minimal examples.  I'm not sure how jsfiddle could be used more efficiently -- does anyone have experience with that?

No experience, but it seems to me that that might be overkill for many of the examples.

Generally speaking, important and frequent examples could eventually make it into the test folder in the main repository -- and then they definitely deserve some documentation, (both in the code and about the code in the docs). But if we get them out of the individual emails, that would be step forward.

Agreed.  We may want to consider separating "test" into "test" and "examples" or something like that, since these really serve two separate purposes.  And I don't know if all the examples need to go in the main distribution.

* bug reports

Bug reports should really go to the issue tracker on github but of course sometimes it's not clear that we're dealing with a bug. To be honest, I'm not sure what could be improved.

When people think they're reporting a bug, we should send them over to the tracker, but should we send them over more aggressively, maybe even if we secretly suspect it isn't a bug? (People do search the bug tracker.)

I kind of prefer people posting to the forums and having us create the issue trackers.  You are right that it's not always clear whether something is a bug or not, and many people don't give good titles, so it is hard to use them later on (though they could be edited to improve them, I suppose).  We may also need some more labels to deal with things like feature requests, and such.

* double posts on other platforms

I see more questions showing up on StackOverflow these days. I think that's a great idea for questions that fit on SO. The SE platform is very well designed to identify helpful answers and rank questions of importance --  and the community is more diverse.

What's a bit annoying is that we also have to deal with double posts -- which could be avoided if people were aware that a lot of regular users here are also checking SO systematically (and other platforms). Maybe we should be more active about pushing people to other platforms that we cover? 

This has bothered me as well.  I've tried to link some of the double-postings back to the forum or issue tracker (and the reverse) so that the link between the two is maintained, but I haven't been particularly thorough about that.

I don't think we can prevent double-posting, but we could have a statement about it in our forum "etiquette" post (should we make one).  That is also a place where we could mention that we cover SO and MSE pretty closely as well.

(Btw, there was a discussion on TeX.SE a while back and agreement was that MathJax questions should be on SO, and only move to TeX.SE if they really are TeX questions, not "TeX syntax as emulated by MathJax" questions).

The TeX.SE folks have been pretty adamant that, and they are probably right.  MathJax questions get shut down pretty quickly there.  SO and meta at Math.SE are two places where they seem to be welcomed.

Davide

[David Carlisle]

On 25 November 2012 22:33, Davide P.Cervone <dp...@union.edu> wrote:
>
> The TeX.SE folks have been pretty adamant that, and they are probably right.
> MathJax questions get shut down pretty quickly there. SO and meta at
> Math.SE are two places where they seem to be welcomed.

The MathJax tag at tex.sx now has explicit pointers to stack overflow
and mathjax.org

http://tex.stackexchange.com/tags/mathjax/info

So if you decide that that there is another initial point of contact
for mathjax queries, or if that text
needs updating in any way let us know and we can update it. (I am a
"trusted user" at tex.se for some reason:-)

David


--
http://dpcarlisle.blogspot.com/

[Davide P. Cervone]

Thanks, David.

Is it possible to add a link to the MathJax User's forum at

https://groups.google.com/forum/#!forum/mathjax-users

as well, or is it best to keep links within the SE community? Also,
the link to webmasters doesn't seem to work for me (I think it is
stackexchange not stackoverflow).

Davide

[David Carlisle]

I'll check. (I have edit rights but I dare not edit without passing it
by the other regulars and/or moderators:-)

David


--
http://dpcarlisle.blogspot.com/

[David Carlisle]

I edited it, hopefully that's OK (certainly fixing the broken link must be OK:-)

David

[Davide P. Cervone]

Thanks again.

I hate to be a pest, but I think "informations" should be
"information" (singular), and that that sentence needs a period at the
end. Other than that, it looks great.

Davide

[David Carlisle]

On 26 November 2012 00:20, Davide P. Cervone <dp...@union.edu> wrote:
>
> I hate to be a pest, but I think "informations" should be "information"
> (singular), and that that sentence needs a period at the end. Other than
> that, it looks great.

fixed
--
http://dpcarlisle.blogspot.com/

[Peter Krautzberger]

Hi everyone,

Despite this being an ancient thread, I never quite forgot about it. We've created a community wiki at https://github.com/mathjax/mathjax-docs/wiki. All you need to edit is a (free) github account.

See also the new sticky post with guidelines for postings on the User Group -- https://groups.google.com/d/msg/mathjax-users/Dhk3bQgThaM/NPtq7VLv-5EJ

Peter.

[Dayal Purohit]

How about Google+ community for users to help each other. Does not have to be 'official' support community.

d^3p