update docs

.github/ISSUE_TEMPLATE.md

@@ -17,15 +17,19 @@ Otherwise, you can post here for:
 Some typical questions that we DO NOT answer:
 
 + "Could you improve/implement an example/paper ?" --
+
   We have no plans to do so. We don't consider feature
   requests for examples or implement a paper for you.
   If you don't know how to do something yourself, you may ask a usage question.
 + "The examples do not perform as expected after I change the models/dataset/parameters/etc."
+
   Tensorpack maintainers make sure the examples perform well without modifications.
   But it's your job to pick the model and parameters that are suitable for your own situation.
   We cannot help with such questions unless they appear to be a bug in tensorpack.
+
 + "Why my own model doesn't perform well?", "I don't understand this paper you implement.",
   "How should I change the parameters for my own dataset?"
+
   We do not answer machine learning questions.
 
 

.github/ISSUE_TEMPLATE/unexpected-problems---bugs.md

@@ -32,6 +32,14 @@ You can run a command with `CMD 2>&1 | tee logs.txt` to save all stdout & stderr
 For example, CPU/GPU utilization, output images, tensorboard curves, if relevant to your issue.
 
 ### 3. What you expected, if not obvious.
+
+If you expect higher accuracy, only in one of the two conditions can we help with it:
+(1) You're unable to match the accuracy documented in tensorpack examples.
+(2) It appears to be a tensorpack bug.
+
+Otherwise, how to get high accuracy is a machine learning question and is
+not our responsibility to figure out.
+
 ### 4. Your environment:
   + Python version:
   + TF version: `python -c 'import tensorflow as tf; print(tf.GIT_VERSION, tf.VERSION)'`.

.github/ISSUE_TEMPLATE/using-understanding-tensorpack.md

@@ -28,6 +28,7 @@ Some typical questions that we DO NOT answer:
   Tensorpack maintainers make sure the examples perform well without modifications.
   But it's your job to pick the model and parameters that are suitable for your own situation.
   We cannot help with such questions unless they appear to be a bug in tensorpack.
+
 + "Why my own model doesn't perform well?", "I don't understand this paper you implement.",
   "How should I change the parameters for my own dataset?":
 

examples/FasterRCNN/README.md

@@ -13,7 +13,7 @@ with the support of:
 + [Group Normalization](https://arxiv.org/abs/1803.08494)
 + Training from scratch (from [Rethinking ImageNet Pre-training](https://arxiv.org/abs/1811.08883))
 
-This is likely the __best-performing__ open source TensorFlow reimplementation of the above papers.
+This is likely the best-performing open source TensorFlow reimplementation of the above papers.
 
 ## Dependencies
 + Python 3.3+; OpenCV
@@ -63,12 +63,12 @@ Some reasonable configurations are listed in the table below.
 
 To predict on an image (needs DISPLAY to show the outputs):
 ```
-./train.py --predict input.jpg --load /path/to/model --config SAME-AS-TRAINING
+./train.py --predict input.jpg --load /path/to/Trained-Model-Checkpoint --config SAME-AS-TRAINING
 ```
 
 To evaluate the performance of a model on COCO:
 ```
-./train.py --evaluate output.json --load /path/to/COCO-R50C4-MaskRCNN-Standard.npz \
+./train.py --evaluate output.json --load /path/to/Trained-Model-Checkpoint \
     --config SAME-AS-TRAINING
 ```
 
@@ -83,7 +83,6 @@ All models are fine-tuned from ImageNet pre-trained R50/R101 models in
 All models are trained with 8 NVIDIA V100s, unless otherwise noted.
 
 Performance in [Detectron](https://github.com/facebookresearch/Detectron/) can be roughly reproduced.
-FPN models are sometimes slightly worse, which is mainly due to batch size.
 
  | Backbone                    | mAP<br/>(box;mask)                                             | Detectron mAP <sup>[1](#ft1)</sup><br/> (box;mask) | Time (on 8 V100s) | Configurations <br/> (click to expand)                                                                                                                                                                                                                                                                                                                                                                        |
  | -                           | -                                                              | -                                                  | -                 | -                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -110,6 +109,7 @@ FPN models are sometimes slightly worse, which is mainly due to batch size.
 
  <a id="ft1">1</a>: Numbers taken from [Detectron Model Zoo](https://github.com/facebookresearch/Detectron/blob/master/MODEL_ZOO.md).
  We comapre models that have identical training & inference cost between the two implementation. However their numbers can be different due to many small implementation details.
+For example, our FPN models are sometimes slightly worse in box AP, which is probably due to batch size.
 
  <a id="ft2">2</a>: Numbers taken from Table 5 in [Group Normalization](https://arxiv.org/abs/1803.08494)
 

examples/FasterRCNN/model_fpn.py

@@ -197,6 +197,8 @@ def generate_fpn_proposals(
 
         proposal_boxes = tf.concat(all_boxes, axis=0)  # nx4
         proposal_scores = tf.concat(all_scores, axis=0)  # n
+        # Here we are different from Detectron.
+        # Detectron picks top-k within the batch, rather than within an image. However we do not have a batch.
         proposal_topk = tf.minimum(tf.size(proposal_scores), fpn_nms_topk)
         proposal_scores, topk_indices = tf.nn.top_k(proposal_scores, k=proposal_topk, sorted=False)
         proposal_boxes = tf.gather(proposal_boxes, topk_indices)

examples/ImageNetModels/README.md

@@ -50,8 +50,8 @@ See `./vgg16.py --help` for usage.
  |:------------------------------------------|---------------------|--------------------:|
  | 29~30% (large variation with random seed) | 28%                 |               27.6% |
 
-Note that the purpose of this experiment in the paper is not to claim GroupNorm is better
-than BatchNorm, therefore the training settings and hyperpameters may not be the best for BatchNorm.
+Note that the purpose of this experiment in the paper is not to claim GroupNorm
+has better performance than BatchNorm.
 
 ### Inception-BN