Should I add a disclaimer about known issues in my code in the documentation?

Question

I'm writing the documentation for a WordPress theme project that I've been working on for a long time. The theme is usable and stable enough for release. I'm releasing it, plus its documentation and tutorials for free but am charging for support/customization. However, there are some issues with the code (optimization, mostly) that I've been unable to resolve after months of trying. While I've learned a lot about PHP while doing this project, I'm still a novice and I want people to know that I'm aware that my code has these specific issues, and that with support (via donations or them purchasing support from me), I might be able to hire someone in the future to fix these problems.

My question is, should I include a disclaimer that basically states what I just said above in the documentation? So that people are aware right from the start that while my product is usable and I'm confident in it, it still has these known issues that were beyond my skill level to fix? Non-coders would probably not notice the issues much, but more advanced people in the community may...

...or would it be best to not mention the known issues or my novice skill level at all, and wait to see if people bring them up?

Answer 1

We have a standard 'Known Issues' section in our release documentation. I'd say yes.

Answer 2

If you were going to invest money or time in a new acquisition, would you want to know about its limitations? Probably, so make that information available. You might lose one or two potential users who consider the known issues showstoppers, but they're people who would have got frustrated when they discovered the issues anyway.

Answer 3

Yes, it's always good to have a known issues section; if nothing else, to keep your inbox empty of the same emails complaining about the same bugs you already know about.

Answer 4

In my opinion, you should just list all of these issues/bugs and state that you are currently trying to fix them. You don't want to be bombarded with e-mails of issues you already know about.

Answer 5

would it be best to not mention the known issues or my novice skill level at all, and wait to see if people bring them up?

I can bet they will come up. Don't think that they will not come across these issues. Better to publish the known issues. It should have sections one is things to avoid and then if the user does that, what the user should do to come out of it. If I am paying for any software I would certainly like to know what are the limitations first.

Answer 6

Definitely Yes! A well-informed user is better than a frustrated one!

Answer 7

Treat your customer the way that you would want to be treated.