Focal Point Banner
Community Center Education Summit Technical Support User Groups
Let's Get Social!

Facebook Twitter LinkedIn YouTube
Focal Point    Focal Point Forums  Hop To Forum Categories  WebFOCUS/FOCUS Forum on Focal Point     [SOLVED] document control practices
Go
New
Search
Notify
Tools
Reply
  
[SOLVED] document control practices
 Login/Join
 
Member
posted
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>,


WebFOCUS 8.0.0.2
Windows 7
SQL 2012 / DB2 / etc.
 
Posts: 9 | Location: United States | Registered: November 02, 2010Reply With QuoteReport This Post
<Kathryn Henning>
posted
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
 
Reply With QuoteReport This Post
Platinum Member
posted Hide Post
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.


WebFOCUS 8.2.06 mostly Windows Server
 
Posts: 202 | Location: Johannesburg, South Africa | Registered: September 13, 2008Reply With QuoteReport This Post
Member
posted Hide Post
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)


WebFOCUS 8.0.0.2
Windows 7
SQL 2012 / DB2 / etc.
 
Posts: 9 | Location: United States | Registered: November 02, 2010Reply With QuoteReport This Post
Member
posted Hide Post
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.


WebFOCUS 8.0.0.2
Windows 7
SQL 2012 / DB2 / etc.
 
Posts: 9 | Location: United States | Registered: November 02, 2010Reply With QuoteReport This Post
Expert
posted Hide Post
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.
 
Posts: 3040 | Location: Middle Tennessee [8204M Gen48 in Test&Prod] | Registered: February 23, 2005Reply With QuoteReport This Post
Member
posted Hide Post
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 Frowner , 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. 


WebFOCUS 8.0.0.2
Windows 7
SQL 2012 / DB2 / etc.
 
Posts: 9 | Location: United States | Registered: November 02, 2010Reply With QuoteReport This Post
Platinum Member
posted Hide Post
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


Vivian Perlmutter
Aviter, Inc.


WebFOCUS Keysheet Rel. 8.0.2
(Almost) 1001 Ways to Work with Dates thru Rel. 8.0.2
Focus since 1982
WebFOCUS since the beginning
Vivian@aviter.com

 
Posts: 191 | Location: Henderson, Nevada | Registered: April 29, 2003Reply With QuoteReport This Post
Platinum Member
posted Hide Post
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.


WebFOCUS 8.2.06 mostly Windows Server
 
Posts: 202 | Location: Johannesburg, South Africa | Registered: September 13, 2008Reply With QuoteReport This Post
Expert
posted Hide Post
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,




In Focus since 1979///7706m/5 ;wintel 2008/64;OAM security; Oracle db, ///MRE/BID
 
Posts: 3811 | Location: Manhattan | Registered: October 28, 2003Reply With QuoteReport This Post
Expert
posted Hide Post
susannah, I like that _0 idea!


Francis


Give me code, or give me retirement. In FOCUS since 1991

Production: WF 7.7.05M, Dev Studio, BID, MRE, WebSphere, DB2 / Test: WF 8.1.05M, App Studio, BI Portal, Report Caster, jQuery, HighCharts, Apache Tomcat, MS SQL Server
 
Posts: 10577 | Location: Toronto, Ontario, Canada | Registered: April 27, 2005Reply With QuoteReport This Post
Guru
posted Hide Post
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.


WebFOCUS Server 8.1.05
Windows 2008 Server
WebFOCUS AppStudio 8.1.05
Windows 7 Professional
IE 11 and Chrome Version 43.0.2357.124 m.
Mostly HTML, PDF, Excel, and AHTML
 
Posts: 272 | Location: Kalamazoo, Michigan | Registered: September 30, 2010Reply With QuoteReport This Post
Member
posted Hide Post
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.


WebFOCUS 8.0.0.2
Windows 7
SQL 2012 / DB2 / etc.
 
Posts: 9 | Location: United States | Registered: November 02, 2010Reply With QuoteReport This Post
  Powered by Social Strata  
 

Focal Point    Focal Point Forums  Hop To Forum Categories  WebFOCUS/FOCUS Forum on Focal Point     [SOLVED] document control practices

Copyright © 1996-2018 Information Builders, leaders in enterprise business intelligence.