About

mFabrik Blog is about mobile and web software development, open source and Linux. We tell exciting tales where business, technology, web and mobile convergence.

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.

RFC: Simple Internet Question Asking Protocol (for human beings)

This is my  attempt version 0.1 to teach the world how one should ask questions in the simplest possible way in Internet discussion. To make it simple, I try to keep this short. This post sprouts from my frustration from the lack of people’s ability to form questions one could easily answer.

Assumptions

If you want to ask a question in forum, IRC (chat) or mailing list

  1. Assume people are busy
  2. Assume that people want to help you, even though they are busy, since they volunteer to participate the community discussion and thus they must care about the community

To make it win-win situation, you as the question maker, are responsible of making the process of asking the question and answering the question as easy as possible. Form your question in such a way that it is as easy as possible for the readers to place themselves into your situation and think how they would themselves solve the situation (Mikko’s rule of empathy).

The less time it takes to undestand your situation the more likely people are willing to contribute their time.

Question process

Thus, I propose that you always follow the simple three steps when asking a question

  1. Before asking the question tell what you already know
  2. Describe the problem
  3. Ask what you do not know yet

Then wait patiently for the answer (the busy part).

Pitfalls

These issues often stem from the fact that the person asking the question is not familiar with text-based communication where people’s time (bandwidth) is limited and the lack of body gestures often leads to misinterpretations.

  1. Do not ask yes / no questions. You are skipping steps #1 and #3.
  2. Do not saturate the bandwidth: do not repeat yourself or otherwise flood the medium. If people are busy it it does not make them un-busy by repeating yourself. You are breaking the assumption #1.
  3. Do not try to pull excessive attention on you – do not try to highlight your question like “PLEASE HELP !!!!” Even if it is a matter of life and dead for you it is not for the other people who are dealing with their own matters of life and dead. You are breaking the assumption #2.

Example

Q: Is it possible to fly me to the Moon? A: Yes

Q: I am an evil super-villain whose plan overtake the world failed.  Now I must escape. I am looking for methods to take me to the Moon or the orbit where national laws to do not apply. I am not sure should I use a shuttle or a rocket. Where could I obtain such a vehicle?

A: US of A just retired one reliable space shuttle what you could use. But if I were you I’d consider underwater base instead, as they will become cheaper in long run, since you can more easily produce breathable oxygen.

More info

Get developers  Subscribe mFabrik blog in a reader Follow me on Twitter

Lazily load elements becoming visible using jQuery

It is a useful trick to lazily load comments or such elements at the bottom of page. Some elements may be loaded only when they are scrolled visible.

  • All users are not interested in the information and do not necessary read the article long enough to see it
  • By lazily loading such elements one can speed up the initial page load time
  • You save bandwidth
  • If you use AJAX for the dynamic elements of the page you can more easily cache your pages in static page cache (Varnish) even if the pages contain personalized bits

For example, Disqus is doing this (see comments in jQuery API documentation).

You can achieve this with in-view plug-in for jQuery.

Below is an example for Plone triggering productappreciation_view loading when our placeholder div tag becomes visible.

...
<head>
  <script type="text/javascript" tal:attributes="src string:${portal_url}/++resource++your.app/in-view.js"></script>
</head>
...
<div id="comment-placefolder">

 <!-- Display spinning AJAX indicator gif until our AJAX call completes -->

 <p>
 <!-- Image is in Products.CMFPlone/skins/plone_images -->
 <img tal:attributes="src string:${context/@@plone_portal_state/portal_url}/spinner.gif" /> Loading comments
 </p>

 <!-- Hidden link to a view URL which will render the view containing the snippet for comments -->                       
 <a rel="nofollow" style="display:none" tal:attributes="href string:${context/absolute_url}/productappreciation_view" />

 <script>

 jq(document).ready(function() {

   // http://remysharp.com/2009/01/26/element-in-view-event-plugin/                                        
   jq("#comment-placeholder").bind("inview", function() {

     // This function is executed when the placeholder becomes visible

     // Extract URL from HTML page
     var commentURL = jq("#comment-placeholder a").attr("href");

     if (commentURL) {
     // Trigger AJAX call
       jq("#comment-placeholder").load(commentURL);
     }

   });                                     

 });     
 </script>
</div>

Get developers  Subscribe mFabrik blog in a reader Follow me on Twitter

How do you prefer your documentation?

Lately there have been three long email chains related to Plone development documentation here, here and here (total ~100 messages). This little post tries to summarize the current discussion.

I think the dicussion is mostly fueled by third party developers’ frustration with the current development documentation situation. Developing for Plone is difficult, since finding references, how tos and examples for those little things you need is very hard. This is a turn off for many developers who would otherwise use this great system – high developer learning curve and gaps in the documentation makes the system useless.

Points everyone agree are

  • Plone development documentation is not good
  • Sphinx is good for API documentation – already happening
  • Contributors are needed

Points discussed are

  • Should developer documentation be more open ended (Wiki-like). This covers
    • Developer manual
    • How tos and other misc. references
    • API documentation
  • Mostly, it is not about generic end user, admin or system integrator or getting started documentation (here, here)

Pro wiki-like documentation stances

  • It should be more open ended (here, here, here)
  • It’s better to have something messy instead of nothing at all – the current approval process discourages contribution (here)

Con wiki stances

  • It should not be open ended, since this results to messy documentation (here, here)
  • There should be less plone.org documents (here)
  • Wikis are bad (here)
  • Incomplete wikis are discouraging (here)

Let’s wait and see where this goes.