I’m seeking guidance related to best practices or uses for ‘document control’ related to procedures (FEX) and HTML files.


Currently, a standard text note might be created for each "report request" stipulating something like: Regarding Report Request ID#: “12345”, FEX filename “A”, FEX filename “B”, and FEX filename “C” are used within HTML file “Alpha-drill”. Requested input parameters are for a date range with assigned amper variables '&STDATE' and '&ENDDATE'; this report offers abilities to drill in to retrieve '&USER' and/or '&ACCOUNT' details.


Any ideas for tools, template, or processes that are known to support existing doc control specific to WF would be appreciated.


WF's "Impact Analysis" is only so useful and it can fail if 'renaming' is performed after creation.

Up until now, our Request For Change [RFC] forms with attached text notes have supported this need. However, it has left my growing department exposed to 'tribal knowledge' support.

Thank you kindly!

This message has been edited. Last edited by: <Kathryn Henning>,

Hi Michael,

Are you using a vendor-provided document management system or something written in-house? How are these "text notes" created
and stored?

Regards,

Kathryn

Hi Michael,
I may not be fully grasping what you're after - but a process that we found fairly successful when working at sites that did not have a formal change control/version control system (e.g. a system that would check fexes out/in and promote them from Dev to QA to Prod), was to include notes in the fexes.
We defined a standard on how to include "notes" in a fex. For example:
If the fex line started with the characters
-*[n]
then it would indicate a note.
The note could have a further "structure" to it e.g. to include the Request ID, date and initials. So your notes could result in the following fex lines.

-*[n] 12345 20130731 TJ FEX filename “A”, FEX filename “B”, and FEX filename “C” are used within HTML file “Alpha-drill”. 
-*[n] 12345 20130731 TJ Requested input parameters are for a date range with assigned amper variables '&STDATE' and '&ENDDATE'; 
-*[n] 12345 20130731 TJ this report offers abilities to drill in to retrieve '&USER' and/or '&ACCOUNT' details.

Notes could be between lines of code, or added to the very bottom of the fex.
We then created a Master File Description that could read our fex, and a utility fex that would allow one to produce documentation of a selected fex, or of all fexes in an app directory.
If one just wanted to print the notes for a specific fex, then it would be reading the physical file on disk.

The main challenge with this approach is the discipline of the developers! But there are ways to manage & monitor that too.

Kathryn, to better express my situation, I’m not using a Vendor-Based software for any ‘doc control’ or our ‘Change Management’ processes.


Like most organizations, when a business unit needs a report (built from WebFOCUS) they will submit a “Report Request Form” (e.g. SharePoint Form) detailing the report requirements and purpose.

That ‘form’ supports the cradle-to-grave (development/delivery) of the request itself.

In my premise, three WebFOCUS ‘procedures’ were created to fulfill that requested functionality, all of which are associated on a single ‘HTML’ file, which is presented on a WebFOCUS ‘portal’ (with applicable security).

Ideally, and assuming no modification are ever needed, the report is stable and the request form is deemed “completed”.


The remaining need I express here falls into expanding the premise further down a timeline… say the developer that constructed the three FEX & single HTML file leaves the organization (thus the ‘tribal knowledge’ is unavailable).

What is or should be in place for the new/replacement team member, who is assigned an Application Directory [containing hundreds of FEX & HTML files] and needs to quickly assess:

What files (FEX, HTML, INCLUDES, etc.) tie together
‘the purpose of the specific WebFOCUS file’
‘what “Report Request Form” does it support’
any applicable aesthetics (screen shots of graphical layouts)

While Twanette’s solution to add ‘comments’ (notes) within each file can address most of the need presented in this post, that would solve only at a micro-level (one file at a time). As stated, the “discipline of the developers”.

Following the premise of ‘losing a developer and a replacement coming in’, it can be incredibly time consuming for the newbie to be required to OPEN and READ each file (in essence REVERSE ENGINEER each single file to determine its connections).
This practice is almost never cost-effective, especially if efforts were already exuded to put ‘comments’ in place. I’d think there would be some type of ‘association’ tool [a.k.a. “tagging”) available.

Barring WebFOCUS offering one, my post is to ask what other’s are doing to compensate.

Twanette's suggestion is a great start and I've seen it in place in many organizations. I would also add to those comments (in a "flower box" - from the good ol dayz) atwo lines: 1) "Called from" (procedure), and 2) "Calls" (procedure). Of course the initial "notes" refers to the "Report Request Form" which should include a section referred to as "Developers Notes". the “discipline of the developers” will remain an issue as long as the organization allows it to exist.

Well to make sure I manage, “discipline of the developers”, I need to have a process in place that WHEN they follow, will provide quick ‘searchable’ results. My desire is to get in front of the ‘reverse engineering’ requirement that too often pops up when labor-shifts occur.

Whether developers take notes, insert comments to the code, or we utilize “tagging” in some manner outside of WF , there has to be an offering which the majority of WF customers could benefit from.

After seeing all the capabilities in other software tools which help users organize music, photos, documents, etc. on almost any platform, I remain optimistic that WebFOCUS could construct something that would avoid having to “open” every file let alone “read” through every comment.

Then again, this issue has existed for at least the three decades I’ve been involved in data & query management… so perhaps this is just an ‘itch that will never be scratched’

My sincerest appreciation goes out to all those that offered suggestions (both in this forum and by reaching out privately). To date, it still feels like a piece of doc control (“tag” tracing/searching) is missing from the product.



FYI: Running “Impact Analysis” on a synonym/data sources appears to convey connections of the files, so my ‘data management’ doc control needs are covered. But in at least the 8.0.0.2 version, I’ve already uncovered circumstances where connections were not properly identified when IA was executed. 

Michael,

You bring up an excellent issue and one that I have grappled with in several organizations over the years. I have at times built Focus databases and at others Excel spreadsheets to track the development of a "system" or application(s). Documentation always seems to be the last thing that anyone wants to do, but it is the thing that the department ends up paying for the most at the end of the day. The time it takes to tracks down Focexecs, Html files, scripts, etc can be managed with some proper upfront planning. And, worse, when a change is made, the cascading results are not known until something does not run.

Vivian

Hi Michael,
Regarding your comment:

quote:

... something that would avoid having to “open” every file let alone “read” through every comment.

We specifically used this mechanism to avoid the above. The specific standards in the fex e.g.
-*[n] for notes
-*[d] for documentation
-*[l] for links or dependencies between components
e.t.c.
allowed us to build the WebFOCUS utility fex to run reports off our app directories, which would document the relationships etc.

hmmm...
i like that idea.
what i use and have used since Noah built the ark,
if i have, say, 4 files for a project, they are titled:
projectname_fs.htm (the frameset for the presentation)
projectname_launchpage.htm
projectname_hostreport.fex
projectname_ddlist_1.fex (for dropdown lists)
projectname_report_2.fex (maybe a drilldown)
projectname_report_3.fex (maybe another drill)
projectname_0_documentation.fex
...
its this last one, the 0_documentation.fex
which is a text file i write everything on earth i need to know. it doesn't execute; it just sits there. the naming 0_documentation assures that it sorts FIRST in the order of the projectname's group.
simple, but works for me.
i'm going to adopt Twanette's internal nomenclature tags..i like that!

This message has been edited. Last edited by: susannah,

susannah, I like that _0 idea!

We started developing in projects so that the html launch page and all of it's fex's are contained within the project and can be deployed together.

Let me thank all who offered suggestions and comments.

I look forward to seeing what enhancements come to fruition which make doc control even easier to manage.