Re: Basic User Manual for Nabble

Posted by nnako on Apr 19, 2014; 10:56am
URL: https://support.nabble.com/Basic-User-Manual-for-Nabble-tp7589558p7590078.html

Hi again,

sorry to disturb again. I just want to encourage you Nabble people again, to think about extending your activities regarding documentation of NAML. It seems to be a mighty tool in the hands of people who understand the concept and know where to look for the bits they need in order to build sophisticated web applications.

Here my view of the current documentation status

The introduction to NAML tutorial is a great introduction of the NAML system. The language introduction is clear and understandable. It seems to be perfect for getting a practical idea of how to use NAML in general. Together with the gallery example tutorial, the introduction is perfect and motivating. The macro parameter description, especially regarding the "dot parameter", is quite short. As this subject seems to be the key to understanding NAML's flexibility, more detail and further examples might be useful. The description for overriding a macro is very good and practical. Maybe other activity descriptions would be great as well; not just the overriding of existing macros. The section about namespaces and the stack is empty. I guess, information about the structure was intended to be placed here. The help pages hold some basic information for maintainers and users of the different applications. Here, structurizing the topics and adding of condensed solution posts from the support forum would be helpful. It could evolve as a central usage manual.

Within the documentations mentioned above, a handful of parameters and some structural information is available. Now, a kind of "reference manual" which covers the following items would be a great help for developers who rather "do" than "ask":

- overview of how to use ALL the flow control concepts (e.g. if, while, case, loop,...)
- overview of ALL "variables" the programmer can access (e.g. the current user's name, subscription status,...)
- overview of ALL usable Nabble commands (e.g. "overridden",...)
- concept explanation of the "requires" parameter in macro definitions and an overview of ALL possible members
- structure descriptions to see relations between macro functions and page outputs (cause and effect)
- ...

Just tell me. I'd like to support.