Hi all,
Within our organisation we create a lot of scripts for (mostly) Revit & Civil3D, unfortunately most of them are used very scarcely since my colleagues don’t know they exist, how they work and what they do in general.
Therefor I am wondering, how do you all document your scripts, share them and make others use them. Also, what do you and do you not include in this documentation?
Yes Daan…in my opinion its the most difficult task…more difficult then make the graph/script itself 
Make them earn extra points for a free day off? 
yes offcoarse…here we have the solution
@Daan ,
the best script documentation is when it is embedded in a usecase.
f.e. fassade - FamilyInstances based on types placing
roombook parameter filling
PyRevit office costum interface
…
WIKI dynamo usescase library would be nice.
the book Beyond Dynamo is already a small step in this direction.
KR
Andreas
Where I work we use sharepoint and I manage a computation wiki. Each script we build has a short wiki and demo video. In my pyrevit toolbar i have a tool which has a manually generated list of script functions/names which then opens the URL and takes them to that wiki.
Generally if people aren’t interested in automation it’s hard to get them on board just using wikis/docs. Consider putting on lunch and learn sessions and record them for company future reference maybe?
yeps that hits the nail
Hola amigos. Once I tried to document my scripts in detail but the truth is that I didn’t make it an habit, what I do a lot is to group nodes and give them a good title and sometimes a description, I guess it counts as documentation.
I think its more complicated as so…right now i think in many firms, really dont understand how powerfull dynamo is,at least if you work in autodesk but there are many ways to goal…its seems to go in two tracks here where we try get users to use finish graph vs teach them how to do it…
What kind of information/ structure does one of those wiki pages generally have?
I also have some video material of me running the scripts aswel 
, will surely use that too!
–
@gilberto.arechigaiba We already have a sort of template for these kinds of things. However this is not the documentation I’m working on right now, since this is only for fellow developers and will/should not be seen by the non-developer users
to get the rewards when you are on the right path.
My recomendation after spending A LOT of time in writing dynamo documentation: Don´t do it 
People won´t read it, at all. They instead will click around until the tool does what they want it to do.
So I started to build the scripts like the users want them to be. User Interface is the key. If you run a script you get a message that tells you what the script does, if you have to select something before running, etc.
So the scripts can be used without any knowledge, you can`t use them wrong and if you do a message tells you what to do instead.
So my suggestion is:
Example:
Script name: View_Duplicate
Run without selection:
Info message opens, “Select a view on a sheet before running the script. Also works for legends and schedules. (Tip: You can also select the section line or select the view in the project browser.)”
Run with wrong selection: same info message opens with headline: “No view selected.”
Run with right selection: script runs.
In my opinion, all documentation that is needed is a list with all script names and description of the function in about 10 words max.
Edit:
Thats how i did my documentation that no one ever read.
I think we are beyond that
Dynamo has proved to be more cost effective, taking less time to do what is needed, as long as the graph is reusable (in not just one project)
a big thing is building engagement, and helping users feel like they have input and an impact on the tools they have available to them.
someone mentioned user group discussions: i think this is a good way to get people acquainted, and build engagement. another way is to engage with teams during the BIM Kickoff to identify tools they might want, or processes that could be automated.
the tricky thing with dynamo is constructing tools that are general enough that people can use them in robust ways. often, a script will be incredibly narrow, if not project specific, and it may not be intuitive for a user to even think to look for it. If the user can break it, then it’s not trustworthy and they won’t feel comfortable incorporating it into their process. From my experience, dynamo is pretty poor at real, dynamic, exception handling and this could easily become a barrier using Dynamo as the platform for firm-wide process enhancement/automation.
building documentation is fine, but it’s still an impersonal level of interaction, similar in function to the oft elusive ‘BIM Standards’. “Let’s take a look at what you’re trying to do” is probably going to click better than “did you check the documentation”. reading documentation sucks and is boring.
As far as providing easy access for users and making documentation available and discoverable, I’ve used Orkestra and it does a pretty good job of providing a searchable library, linked documentation, and a dedicated ribbon. It presents some issues when you try and load up too many packages, but YMMV.
In my case the scripts all follow a naming structure of Category_Name, so my page is divided into categories and has an index for each to quickly jump to a guide.
The guides themself are a paragraph summarizing the script function, and sometimes notes aboud key limitations or reauirements. I also list supported builds as some are 2023 only for example.
Gerhard is correct in that without a means of getting engagement as well as building scripts to suit the more trigger happy/low reading users, the wikis arent enough alone to support the firm.
User engagement meetings are one way, and I also have logging ties to my scripts so I can see when a new user runs a script for first time, and from there I usually engage in a quick chat (assess their experience, if theyd like training, their goals for using dynamo etc.).
Another reason I like pyRevit.
Any help file can be just dropped in the same directory as the script. It can be a text file, link to web site, a PDF, a Word document or YouTube video.
Highlight icon. Hit F1. Done.
I’ve struggled with user adoption as well. I couldn’t have made it easier for folks: Dynamo Player library all synced up, deployed script dependencies, custom Revit ribbon with link to SharePoint documentation pages. But still scripts were just sitting there, unused.
I’ve currently shifted my efforts to teaching. Last year I led an automation focused Dynamo class where the participants created their own scripts for tedious tasks they encounter on a regular basis. I then took the results and scaled them up to share with the firm. This year, I’m teaching a computational design Dynamo class, exposing folks to form finding in Dynamo, adaptive component placement, and Generative Design workflows. A less practical use of Dynamo for our firm, but flashy enough workflows to help people experience the potential of Dynamo/Revit in a more exciting, conceptual environment.
So, structure first, to prepare for the scaling of Dynamo if adopted, then training. However, these are not suggestions, as I’ve merely planted the seed, but I’m hopeful that consistency over time will promote growth.
I think this article summarizes the struggle in a somewhat optimistic way.
Thanks everything for all the quick and really insightful feedback! I’ll work on some ideas this week and talk to some colleageus, will post my conclusions/ results later
I write monthly updates on our company’s automation process.
So when new scripts are developed, I write an email with screenshots and explanations as to what it does and why it should be used. I try not to get technical in here as those who don’t like automation will be put off by reading a technical explanation. I just show the input and result of a script and create a small PDF file as tutorial if needed (for complex graphs).
