Back in the days…
Oh, let the old man talk…
10+ years ago, there were basically two discussion boards for Epicor-related products: The Yahoo!Group and the Epicor Users Group. There were some other sources scattered around the web like the SpiceWorks Forum and individual efforts like Ginger Help. And of course, there was EpicWeb, and now EpicCare.
The thought was:
“Wouldn’t it be helpful if there was an easy way to find Epicor information without having to have to go to each source to get the answer?”
(The other reason I wanted a different site, unlike EpiUsers.help recently, there was strictly no selling or marketing on the the Yahoo!Group or it was pay to play in the EUG. A wiki could also let entrepreneurs hang out a digital shingle.)
The solutions recorded in this place could also link back to the original source(s). Of course, this is what a Wiki does. The software that runs Wikipedia is called MediaWiki and is free. So I took out a domain, epicwiki.com, and got started. I learned a lot about wiki’s and one of things that makes them successful is the ability for anyone to contribute easily. Single-person cultivated wikis rarely survive. The difficult part is providing some structure to the pages to make it easy for everyday users to contribute. This is where EpicWiki crashed. It was somewhat easy to throw a page up there but every page would look different.
So if you go to https://epicwiki.com, you’ll end up here.
But the problem remains. People come here and ask questions that have already been answered multiple times. The search is fine but you still have to comb through threads and maybe somebody even marked a post as a solution. But like @JasonMcD, one is left with the impression that it could be done better.
So, besides a Wiki, where else can we find a user-contributed help repository? One such place is Microsoft Docs. Microsoft uses an open source tool called DocFX. Like this forum, the entries are comprised of Mark Down, albeit a specialize version called DocFX Mark Down. It takes these mark down files along with a table of contents file and builds a static web site. Because one uses headings, etc., you get a built-in document structure. Each page has a site search, a topic index with filter, and a page index. More importantly, there is an Edit link. When you click on the Edit link, it takes you to GitHub where you can make a change and submit it as a pull request. If they approve the change, it starts a build process and republishes the site. In addition to editing directly in GitHub, you can also clone the repo and use some nice Visual Studio Code extensions. There is previewer, an image manager (compresses your images, a link checker, among others. There is even an extension to write your own Microsoft Learn module.
Once the site is built, it just needs to be deployed to a web server somewhere. The good news is we could use GitHub pages to deploy the site. It’s a nice little DevOps example.
When DocFX first appeared a few years ago, I asked @josecgomez if we could get a public GitHub org. And he did. Did I start the project? I did not. Again, the issue is with creating a structure to make it easy for people to add/maintain content. To me, that seems like a group effort. More importantly, any group is smarter than I am. All of Microsoft’s docs are free to browse on GitHub too if we wanted to copy something.
Oh, one other thing we need to do. We need to be careful with Epicor’s (or any other person’s) IP. This is just a true for EpiUsers.help but I wanted to make that clear.
Everything I have written about here is called “conceptual” documentation, in other words, describing things and processes. Where DocFX really shines is that it can read code or a swagger file and generate documentation from that. That’s beyond the scope of what we’re talking about for EpiUsers.help. Don’t get me wrong. It would be really cool to generate documentation for Epicor components (BPMs, Functions, BAQs, Kinetic Screens/MetaFX, etc.) but we have to crawl before we can walk…