This past year as we’ve developed Sierra and SMB (Saffron Memory Base, our enterprise product) we’ve tried to embrace the power of the web to deliver information to our users. Hosting our documentation online felt like a very natural, and valuable thing to do (still does). We decided to use PBworks to host our documentation. We probably made this decision because Twitter was using it for their online documentation,
As we lived with this solution for a few months we’ve noticed a problem with this approach that continues to haunt us. What’s the problem you ask? Versioning! We need versioning. As we’re developing features and fixing bugs for a new build we often need to update the documentation. We may change something subtle about the JSON that is returned from a REST call. We may add a new request parameter that we didn’t have before. The documentation stays fresh, but unfortunately our customers, both Sierra and enterprise, are not always on the latest build. Sometimes that is due to a choice they’ve made, but often the latest build hasn’t even been released. Either way we end up confusing our customers in an effort to keep documentation up to date. We’ve worked with PBworks support and have a strategy for helping with this, but I can already tell that the new strategy will not be perfect. We have customers on many different versions and we need them all to have documentation that matches their version.
Are there other tools that we should look at? We want it to be a hosted solution. We need to for all our developers to be able to edit and contribute. We like the “wiki” approach. Thoughts?
