Troubleshooting Trees
-
Hey All,
I work in support. I support one piece of software (6 historical versions, mostly similar).
The software drives engraving machines.
I am currently the only expert on the software and connections to the machines.
It's time to shift departments and train someone else.
I'd like to try and create an app or document much like a phone support script, which could present questions to ask and then further questions, until providing things to try to resolve the issue.
I'm struggling to find either the right keywords to google, or any real options.
What exists?
-
Forgive me, but it sounds like you'd spend way more time learning and configuring the workflows than you would just writing the documentation.
Have you looked at Confluence? If you don't already have it (and the target audience is ten people or less) then it's a bargaintastic $10 a month, and it's very easy to get a navigable doc set up and running pretty quickly.
-
Sounds like you're looking for process document and procedure document (yes there's a difference).
Once you have the main flows (via the above) then you can work on troubleshooting guides.
But, uh, why isn't this already available? I personally have the excuse that I'm literally the only guy still working on the product and don't have time to update the docs while keeping it running...
-
Personally I'd probably just make something confusing with mermaid.
-
@Tsaukpaetra said in Troubleshooting Trees:
But, uh, why isn't this already available? I personally have the excuse that I'm literally the only guy still working on the product and don't have time to update the docs while keeping it running...
This. We have documents for how to resolve issues, but knowing which document to send to a customer requires a person who knows what they are doing.
Actually using the software is covered by the docs. It's those lovely bugs that will never get fixed that have easy workarounds.
-
@skotl said in Troubleshooting Trees:
Forgive me, but it sounds like you'd spend way more time learning and configuring the workflows than you would just writing the documentation.
Have you looked at Confluence? If you don't already have it (and the target audience is ten people or less) then it's a bargaintastic $10 a month, and it's very easy to get a navigable doc set up and running pretty quickly.It's not documentation we lack. The the means to tell a non expert which document is relevant.
Here's an example...
In versions 5 to 7, it's possible for one of the config files to become corrupt. The developers couldn't find out why.
In versions 5.1-5.3 you have to manually replace the corrupt file. In 5.4 and above there's a button in the options menu that restores a working file.
When the file is corrupt, the software exhibits certain issues, but otherwise works OK.
This means people start their support call with something like "I can't select text, but I can drag select it" or "when I import an image it shows an empty box".
For me, that's a 1 minute phone call. For a non expert they would be very confused.
It took me almost 3 years to learn the ins and outs of the software (and then they went and released a new version which has completely different architecture mixed in with old features from previous versions).
So some sort of flowchart software, but it's not the drawing I'm interested in, it's the process.
-
@Ben_Warre
FAQ style documentation. Write documentation based on answering questions. Why doesn't x work anymore? Answer: The config file might be corrupted. See: restoring a corrupted config file. Other possible causes: ...
How can I restore a corrupted config file? ... Answer: for version x do y ...The question style keeps it short and to the point. It reads easier and support staff will actually be able to use the info in related but not identical cases.
How and where you store that ...
we use a custom cms thingy.
-
Playing with TiddlyWiki.
-
-
@Ben_Warre said in Troubleshooting Trees:
Playing with TiddlyWiki.
Looks interesting. I've been looking for that kind of thing for a while.
-
@Ben_Warre said in Troubleshooting Trees:
Playing with TiddlyWiki.
I was going to suggested something like https://zim-wiki.org/ but TiddlyWiki should serve you quite well.
