I recently saw an opportunity to join one of the UK’s leading Autodesk Platinum resellers, Graitec and the sudden move jogged me into thinking about the tools I have created in my two-year tenure at my current post of CAD Engineer at Matrix Precision Engineering Ltd. based in Thatcham, UK.
In particular, it forced me to begin the sometimes-onerous task of documenting the tools I created along the way. This led me to tweeting the following:
Dotting the i's and crossing the t's before moving onto pastures new. Definitely writing user guides hand-in-hand with development next time
— Alex Fielder (@AlexFielder) June 16, 2015
A week or so passed and there followed another tweet this time regarding the AUGI survey results due to be published shortly in their “Hotnews” segment:
— Alex Fielder (@AlexFielder) June 23, 2015
By this time, I was neck-deep in writing several documents that (I hope) will guide my soon to be ex-colleagues in using the tools I built and, coupled with the series of replies that followed the latest tweet above, the whole situation got me thinking about this post.
When is the best time to start writing documentation/processes and procedures?
For me, documenting the software I’ve written has up until now been a “For my eyes only” approach; wherein I document or more accurately comment the code as needed and do no more than that. As I prepared to leave my previous post (prior to joining Matrix), many of the tools/processes I had created were already out of use, primarily because the project they had been used upon had ended. This time around, the team I am leaving is in the infancy of getting to grips with helping their client understand exactly how they need to use Inventor/Vault Professional alongside their existing legacy data.
This leaves me with a challenge I hadn’t expected to face when I wrote the four main pieces of software, that I now find myself some 75% of the way through writing guides for:
What’s the best way to write a document about something I created, when my intimate knowledge of the subject could lead to many oversights/omissions in the documentation, based on assumed knowledge about a template/pre-requisite?
On this occasion, owing to the fact that we’ve been writing a document aimed at which capturing every intricacy we have encountered on behalf of the clients’ dataset, I chose to use Microsoft Word, stored in an instance of Autodesk Vault Professional 2014.
Whilst it seems on the surface to be a good match, there are multiple issues with doing it this way, not-least the fact that none of my colleagues can see what I’ve added to the file until I either check it back into the Vault or email a copy round for people to make their own notes on. In future, I think I would prefer to use Microsoft SharePoint, as it allows a more collaborative approach not available in Autodesk Vault.
In addition, everyone has their own style when it comes to writing documents of this type, so here are my top tips for writing the best documentation you can:
Is it simply code or a workflow involving multiple steps?
The reason for this differentiation is that if all you have created is (for instance) an Inventor iLogic rule, chances are the complexity of said rule will be such that anyone with a competent understanding of iLogic, should be able to figure out what it is doing based on the minimal amount of comments within the code. This of course depends on the person writing the iLogic using a Really Obvious Code (ROC) approach.
If your creation is more than simply iLogic, there comes a point where commenting the code is not going to get the necessary level of understanding from your audience for them to be able to use the tool in your absence. The technical nature of your workflow determines when and where exactly you reach this point.
When the workflow is:
- get external iLogic rule from Vault
- open file (assembly or part)
- add external rule to Inventor
- run rule
I would say there is little need to document these steps over and above a single page of A4.
If however, the above iLogic example were to rely on other pre-requisites such as Microsoft Excel templates and an understanding of (in our case) the clients’ parts list numbering schema, then there is a benefit to the team in documenting the workflow in its entirety.
Treat the audience as if they are new staff
Unless you’re prone to showing off during your workflow creation, there will be very few staff who will have any idea what the workflow you have created is capable of doing, let alone how it is doing what it does. My advice is to take a view that although the team member using the new process will be competent in their main role/software (in this case, Inventor) anything you have created will be completely new to them.
My current example of this is for a workflow I created that takes a folder structure based on pdf file names, pairs it with an Excel spreadsheet containing the relevant metadata, then builds an Inventor assembly that matches the structure. I quickly figured out a number of steps required to get the data in a useful format, and rename the files (sometimes 1000+) for each project.
What I had overlooked was exactly what tools and pre-requisites I had been using as part of this workflow, it having been some time since I had first installed them. The first draft of my document had skipped over these details because these tools were so ingrained to me that they had become second nature to make it all work.
Ask a colleague to use the workflow (and accompanying guide) on their workstation
This may not always be possible as your office might not have anyone spare to test the documentation, but for the sake of your team, I believe this step is necessary if you are determined to have a robust, user-friendly guide that covers every step required to carry out the workflow correctly.
In the event that you are not able to have someone test the workflow, there are a number of potential solutions available. These range in complexity from simply asking one of your co-workers to swap desks for a period (whilst you complete the guide), to creating a temporary user account on your current workstation (mild difficulty), to setting up a virtual machine on your workstation. Obviously, the last option is fraught with its own issues, but I truly feel all these steps are worthwhile in the long term; especially if you wish to avoid a phone call in x number of months after you departed the company asking you why workflow/tool x has stopped working.
Get to know the tools and document why you used them
Revisiting the software that forms part of the workflow I had been documenting; it is important to note that although the help guides for most software will be comprehensive, it is best to leave nothing to chance. Where possible it helps to explain some of the underlying uses of the technology/techniques you have used, to help the user better understand how it all works. This extra information will aid the team should something change down the line.
The best example I have for this is Regular Expression.
Google defines Regular Expression as:
An example of a simple regular expression (regex) is:
Wherein the “.” Signifies any single character and the “*” matches the previous character zero or more times.
If your workflow finds you needing to work with any kind of text string, be it file names, drawing numbers, or other metadata that contains multiple pieces of information, regex is just the ticket.
As part of my workflow I had a file name that also included the Assembly level of that file:
1-1 DWG-NUMBER Sheet-Number Issue-Number.pdf
Regular expression let me remove the first part with the following simple match:
Wherein the match can be broken down by the https://regex101.com site as:
This returns the following match information:
Which as you can see gives us the correctly named .pdf file (Match 2 above)
In the workflow I have been documenting, regex is useful in both Microsoft Excel (with the addition of the Regex Find Replace Addin) and in the Bulk Rename Utility <- a tool which does exactly as the name suggests.
The addition of extra information such as this makes any user guide so much more useful than simply saying “insert this into this cell and hit enter”, as it builds a level of understanding with the user of said guide that is otherwise not available.
This understanding is useful for future situations not already covered by the workflow or workflows you leant your skills to help create.
If I were to boil these points down into a simple list it would be:
- Make documenting your workflows/tools part of your team’s standard procedure list
- If your workflow involves a software tool you created, assuming you have followed a ROC approach, there should be little need for excessive explanation
- If you make use of a particular technique or piece of software (in this case regex) as part of the workflow, it will help if you explain in detail how and why you used it
- Have a colleague test the workflow using your documentation when you are finished; it will help highlight any areas that need further explanation/detail
If this experience has taught me anything it’s that I should always practice what I preach. I hadn’t really given the documentation a moment’s thought before deciding to move to my new job. Having to write documentation for workflows I knew intimately, forced me to consider in great detail all of the steps I had gotten so used to using along the way, and thanks to my (ex) colleagues’ feedback, there now exists a comprehensive guide for each of the most-useful workflows I have left behind.
Writing all of these points down will hopefully serve as a useful reminder to both myself and you the reader in future.