Attached is a new forena HELP report (in FRX format, with a _.txt extension for now to enable upload to DO). It's related to one of the drupal admin tasks that are required to get the HTML filter configured correctly (eg to avoid problems when trying to display SVG graphs). Please read the content of this file for what it is all about. As a next iteration I'm planning to add more docu to this same HELP report about other Drupal admin tasks.
Since this is a new report, which I think fits in the "Forena Site Administrators Guide", I also added an entry about it in admin_topics.xml, which is located in the forena_help repo that comes with forena. The updated admin_topics.xml is attached also (and also with a _.txt extension for now).
There are other drupal admin tasks that I plan documenting/contributing in subsequent iterations of this new FRX file.
I leave it to the 'forena maestro' (aka David) to consider including it in an upcoming forena release.
To enable the review of this report in your envir, remove the _.txt at the end, and copy them to the appropriate forena dirs.
I'd be curious to receive some feedback about it, such as:
1) does the content topic help (make sense)?
2) how do you like the various links to relevant admin pages in 'your' site?
3) what are the list of similar topics that fit into this drupaladmin help report?
4) anybody interested in joining the "Forena Documentation Effort" by contributing similar help rpts? If so: which topics/areas?
PS: English is not the language I learned on my mother's knees (though I've learned a few English expressions during all the years I worked with some US based companies ...), so please feel free to correct my English where needed ...
| Comment | File | Size | Author |
|---|---|---|---|
| #1 | drupaladmin.frx_.txt | 11.18 KB | Pierre.Vriens |
| admin_topics.xml_.txt | 443 bytes | Pierre.Vriens | |
| drupaladmin.frx_.txt | 2.87 KB | Pierre.Vriens |
Comments
Comment #1
Pierre.Vriens commentedPlease find attached a further enhanced (extended) version of the drupaladmin.frx HELP report. For now there are 3 major topics included, related to these items:
* Forena module upgrades
* To clear or not to clear (the forena cache)
* Text formats configuration
Most of the updates, as compared to the previous (initial) version are inspired by https://drupal.org/node/2121153 , a new support issue created yesterday, about some forena-upgrade-issue which I was able to recreate ... (I recognized it since I had experienced it myself also in the past ...).
While working on this, I noticed the 'orignial'-typo within admin/structure/forena in the 7.x-3.11 version (so for now the same typo is in the attached frx ...).
Comment #2
metzlerd commentedI like where you are going with this, but it seems like these are primarily about installing and configuring forena. So can I suggest that we take the same content and organize it around installing and configuring forena? Some suggested outline headings:
we could name in forenainstall.frx and give it a title of Installation and Configuration.
Set up Report Input Format
..
Create a new SQL repository for custom blocks
...
SVG Graph Installation and Configuration
...
MPDF Installation and Configuration
...
Furthermore, particularly in 7.x-4 we could change the README.txt to refer to this document since after that version the reports will be available from the start.
Comment #3
Pierre.Vriens commentedDavid, your reorg-suggestion is really interesting, I was about to suggest something similar. However, at first I was rather thinking about performing such (major) reorg in the 7.x-4.x (DEV) version, combined with what you consider relevant for retrofitting in the 7.x-3.x version (to ensure the impact to the 3.x version is rather minimal).
Also, after working a bit on these HELP rpts, I've come to quite a few additional topics (outline heading as you call it), inspired by reviewing a couple of times your (great!) videos. To get started "somewhere", and with minimal impact to the existing 7.x-3.x Help rpts structure, I decide to dive into the "installing and configuring" items you've seen so far. Also because of quite a few support request issues that come back multiple times (the text format filters, etc). So delivering such topics 'first' seem to me like quick wins also (which makes it more likely that many will agree to add them already to future 7.x-3.x upgrades (and in 7.x-4.x of course). Here are a few of future topics I'm thinking of:
- Styling forena rpts (skins, CSS, etc)
- Exploring all sorts of SVG graph options (some of them mentioned already in your videos)
- Supported xPath features
- building SQL queries (for SQL dummies)
- 3rd party integrations (libraries such as dataTables, SVG Graph, mPDF, etc).
- Reporting about data blocks in XML format (my favorite one ...)
- Localisation features and techniques (translated reports, skin variables, repos to select parm values, etc)
- Forena based module development (all the forena hooks stuff)
- Drush topics
To take all this a step further, my recommendation would be to split all HELP reports into these major sections, mostly organized by "target audience":
- Forena installation.
- Forena administration.
- Report development guide (creating and editing reports).
- Report users guide (users of forena reports, who only want to complete some parms and get the results, without knowing about the (great) technology behind it all).
Regarding "Target Audience", I think these are the major groups of people somehow involved with forena:
- end users with reporting requirements (who don't want to know about the magic behind it all, they just want rpts and charts)
- drupal site builders (= use forena out-of-the-box)
- drupal front-end developers (= CSS experts with usually minimal PHP knowledge)
- drupal back-end developers (= experts in PHP, Linux, SQL queries & connections, etc)
Obvious there is still a lot of work ahead to deliver all this, a huge business opportunity ahead! Maybe there are forena-fans willing to "co-sponsor" part of this work to speed up things?
Curious to get more feedback on all this ...
Comment #4
metzlerd commentedSounds good... I am a big fan of incremental change. So having a rough outline of where we are going is good, but I think it's best to keep the appetites small to begin with. If you don't mind, I'll change the name to installation.frx and we'll assume that these docs are the starting point for that. I just wanted to get you thinking about organization so that what we build can be incorperated into the 7.x-4.x version without having to completely reorganize them, and also bec
The one question that I have about the outline is the question of how to deal with the user interface vs. frx files. Every feature found in the UI has a corresponding markup syntax in forena whether they be in skinfo files or in the frx files. I have some report developers who are comfortable in SQL but not HTML so they just use the UI to edit reports, but are happy to write the SQL. I have some developers who are most comfortable writing reports in raw .frx files. Then I have some power users that only modify reports based on pre-created data blocks using the UI. They don't know .frx xhtml sytax but might be able to create new reports based on existing datablocks. There are certainly techniques that can only be done via .frx files and don't have user interfaces designed for them.
So I guess my core question is do you have recommendations for how to do the docs should be orgainzed given this. Do we stay "task focused" and explain how to do a task, once via the UI and then again via .frx? Or do we create separate report writers guides one for the .frx enthusiast and one for others.
As food for thought here is my experience of the major categories of users that use Forena that I have met so far:
- end users with reporting requirements (I'm not actually sure there is a neeed for forena specific docs for these. Site builders will write site specific docs for how they use their reports).
- Graphers (= people who are drawn to forena because of it's graphing functionaly... they may or may not have any drupal experience and may be html/javascript/css developers who know no drupal)
- drupal site builders (= use forena out of the box) From my perspective this is mostly the same as your front end developer group.
- non-drupal developers (= developers who know SQL and are trying to use drupal for the first time to make reports out of other databases. may or may not have php or html knowledge)
- drupal back end developers (= Like you said, but I haven't met too many of these who have been using forena).
Comment #5
Pierre.Vriens commentedHere are my additional thoughts/comments on the previoous previous comment ...
- Yes please go ahead to do that rename to installation.frx. While doing so, and if you agree, please "move" the row (with help.drupaladmin) I inserted in repo admin_topics.xml to a separate (new) repo also, eg named install_topics.xml . That way we further reduce the impact of such new frx files to existing HELP frx files. When time is right, we'll decide how to best consolidate/rework (if needed) the existing HELP docu into the new HELP structure. Moreover, we leave all options open for now about the required ACCESS (as currently in the existing HELP repos also).
- You have a valid point about using the UI versus writing FRXs! Seems like a variation of what I called "target audience". My recommendation about how to organize (structure) the docs is rather to "separate" the guides. However, with your permission, I would enhance the XML structure of your forena_help repos, I.e. by (a) renaming "row" to something like "topic", and (b) by adding extra tags like "audience" for each of the HELP frx files and (c) maybe also group related HELP frx files into forena_help subfolders (1 for each corresponding xml repo we end up with). By reworking a bit the way "all" reports are presented currently, into something like a dataTables-based display of "all available HELP topics" (similar to what you already do in /admin/structure/forena ?), you leave it to the forena user to narrow down (via searching the table or sorting its columns) the list of topics to what he/she really want to know about. And/or by adding maybe some appropriate report "parms" (like 'topic' and/or 'audience'), you can take this even a step further. 1 more thought: such structure/architecture also has the advantage that it'll contain some more advanced illustrations of using XML data blocks, xPath expressions, etc (to which you can point in the HELP frxs ...).
- Open question for me right now: what would be the ACCESS requirements for all such HELP rpts, and how to best implement that (E.g.: does it hurt if HELP docs about forena admin topics can be accessed by a none-drupal admin)? Or does anybody have a proposal about how to implement this in Drupal/forena so that the drupal admin can easily overrule the forena delivered ACCESS rules for HELP docu?
- I like your "major categories of forena users", let's keep those in mind as consumers of the HELP reports. Just curious if anybody reading this issue has any other flavor of users that don't fit in any of these major categories yet (if so, please let us know about it).
If I receive a "go" for starting to implement the enhanced XML structure for the forena_help repos, I propose to create a separate issue for doing so (and continue to use this issue for HELP info about Drupal admin tasks).
Comment #6
metzlerd commentedOk I've committed this change.
Lets create separate issues for reorganization. I'd like to do that in the 7.x=4.x branch. New issues can be created for incremental improvements. I don't have any attachment to the XML structures, so we can change those, but since the reports might need changing, but given the amount of work in keeping current i'd like such sweeping changes submitted in patch format, so I don't have to hand roll the changes. More discussion can be had on the relevant issues.
Also lets create an issue to change the permissions model for the help docs. I agree that we need that in order to set up a documentation site. It's a simple change and one that could be included in the 7.x-4.x branch.
Comment #7
Pierre.Vriens commentedDavid, thanks for the commit. Assuming you wanted your commit to refer to this node, it seems like you omitted the first "2" in your node reference.
I just created new issues #2124777 and #2124785.