Stormwater Management Model (SWMM) Information for watershed water quality, hydrology and hydraulics modelers (Note this Blog is not associated with the EPA). You will find Blog Posts and Twitter Embeds on the Subjects of SWMM5, InfoSWMM, InfoSewer, SWMMLive, InfoSWMM SUSTAIN, SWMM4 and SWMM in general.
Subscribe to this blog
Follow by Email
#RTFM and WTFM How to write a fine modeling manual worth reading (ideas)
Note: The following is copied in part from this blog
Once you've determined the scope, and who you're writing to, there are several different kinds of documents that you can write for them. Anne Gentle categorizes them like this:
Like the Getting Started document I mentioned previously, this is the place where you tell users what they need to know before they even get started.
The reference guide is comprehensive and usually pretty dry. This is where terms are defined, functions' input and output are explained, and examples are given. The tone is factual and to the point. There's not much discussion, or conversation. The voice is usually impersonal.
Tutorials hold your hand and lead you down the path. They show you each step, and occasionally sit down on a bench by the path to explain the rationale for a particular step. They are very conversational, sometimes even chatty. The voice is personal; you are speaking to a particular person, defined in the earlier persona phase.
Often linked to from the tutorials, the learning/understanding documents dig deeper. They investigate the why and the how of a particular thing. Why was a certain decision made? How was it implemented in the code? What does the future look like for this thing? How can you help create that future? These documents are sometimes better done as blog posts than as part of the formal documentation, as they can be a serious distraction to people that are just trying to solve a problem.
There's a reason that the Cookbooks are often the best selling part of the O'Reilly technical book catalog. People want solutions, and they want them now. The recipe, or cookbook section of your document, should provide cut-and-paste best-practice solutions to common problems. They should be accompanied by an explanation, but you should understand that most of the cookbook users will cut and paste the solution, and that'll be the end of it for them.
A large part of your audience only cares about solving their immediate problem, because that's all they're getting paid to do, and you need to understand that this is a perfectly legitimate need. When you assemble your new Ikea desk, you don't care why a particular screw size was selected, you just want the instructions, and you expect them to work.
So it's critical that examples have been tested. No matter how trivial an example is, you must test it and make sure it does the expected thing. Many frustrating hours have been spent trying to figure out why an example in the docs doesn't work, when a few minutes of testing would have revealed that a colon should have been a semicolon.
Recipes should also promote the best practice, not merely the simplest or fastest solution. And never tell them how not to do it, because they'll just cut and paste that, and then be in a worse fix than when they started.
One of my favorite websites is There, I Fixed It, which showcases the ingenuity of people who solve problems without giving much thought to the possible ramifications of their solution—they just want to solve the problem.
Yes, error messages are documentation, too. Helpful error messages that actually point to the solution save countless hours of hunting and frustration.
Soffit Level (pipe technology)The top point of the inside open section of a pipe or box conduit. The soffit is the highest point of the internal surface of a pipe or culvert at any cross-section. The soffit is also referred to as the pipe obvert. So it is not quite the Crown of the Pipe. Here is an image I found that hopefully explains it better.
Engine Error NumberDescription ERROR 101: memory allocation error. ERROR 103: cannot solve KW equations for Link ERROR 105: cannot open ODE solver. ERROR 107: cannot compute a valid time step. ERROR 108: ambiguous outlet ID name for Subcatchment
New InfoSWMM linked 2D Link and 3D Node graphics help you understand one of the most critical outputs in any Stormwater, Combined Sewershed or Sanitary Sewershed Network Model the value and timing of how full the pipes and nodes are over time and how this changes during Wet Weather Flow (Runoff or Infiltration Inflow).These new graphs are included in InfoSWMM v 14.6 and InfoSWMM SA V2 (InfoSWMM SA is not an Esri Extension in ArcMap but uses Arc Engine for GIS processing power) has many new graphical and map display tools that help answer the following modeling questions in a easy to understand group of linked Time Track Graph, 2D Graphs and 2D Thumbnails. If you are modeling a Stormwater Network and need to know the d/D or depth over maximum depth over time and at the peak of the Runoff event you can view linked graphs as shown in Figure 1.If you are modeling a Sanitary Network and need to find the d/D for Rainfall Induced Infiltration and Inflow (RDII) you can see the RDII fl…