businessConfig is a program written in Go that turns simple text files containing data about an organization into pretty, intelligently-linked web pages. It is intended to be a tool for anyone who needs to quickly understand an organization, but especially Product Managers or consultants starting at a new company.
The idea is that the Product Manager or consultant sits with people from the organization with laptop in hand, listens to what they have to say, and records all relevant information quickly and easily in text files like the one shown above. The program then takes care of presenting the information in a pleasant and logical way.
This method has the advantage of being very fast and not relying on an internet connection when the information is being recorded (as opposed to a Wiki), and is OS-neutral and takes care of formatting for you (as opposed to a Word document). Additionally, you can commit the files into source control as if they were program files, with all the benefits that brings such as being able to link to tickets and track changes.
Each text file refers to an "entity" within the organization, e.g. a person or a process. The following entities and their connections have been implemented and can be shown in the web frontend:
The program automatically creates sensible links between the entities which are then reflected in the frontend, such as being able to see all members of a team in a list, even though team membership is defined as an attribute of a person. Also, only entities with associated text files are shown in the frontend so that, for example, if your organization doesn't have clients, you won't see the clients option in the website.
The program is written in Go and uses several external packages in addition to the standard library:
cdto the program src directory
./businessConfig -source="Chicago Public Libraries" -init=true -username="AdminMe" -email="firstname.lastname@example.org" -password="mypassword"
./businessConfig -source="Chicago Public Libraries" -port="8081" -dev=true -devlogin=AdminMe
As long as you're using the program locally with the sample files, or with text files you generate yourself, that's all there is to it. Generate your files, run the program to point at your source, and off you go.
I give no warranty for this program since it was written as a learning exercise and I have not yet used it in a production environment. But it is designed to deal with it, and here's how I would go about it.
There are 4 roles to consider once the program is in production:
These roles are relevant for granting access to certain files/directories, as we will see below. Note that the User/Superuser roles are distinct for each data source served by the program, but the templates are SHARED by each data source.
Due to the different requirements of each role, I suggest the following directory structure on the server:
|/businessConfig||resource_dir in settings.go|
|/webclient||Shared only with UI devs|
|/datasource1||Shared with source1 users|
|users.txt||Shared only with source1 superusers|
|/datasource1_runtime||Generated by source1 init command|
|/datasource2||Shared with source2 users|
|/datasource2_priv||Shared only with source2 superusers|
|/datasource2_runtime||Generated by source2 init command|
As noted above, changes to text files and templates are picked up by the program as soon as they reach the server. However, users will be editing files locally, so there needs to be a way to get them onto the server. I envisage this being handled either by Dropbox in an informal environment with 1 or 2 users, or proper source control in a more formal environment with many users who could potentially be editing the same files. In this way, the organization text files are treated the same way as code files, but with the Product Managers making commits. As a last resort, you could of course simply use FileZilla or the like to manually copy files to the server.