Well said. I agree 100%. Clear and concise are critical watchwords for good technical documentation.
When I first downloaded the iPad version, I put it aside because I could not figure out some of the features. I.e. I could not see the value of Doit. After rereading the documentation several times, I started to see the value.
I'm motivated. However many potential customers are not - they will not spend the time to see the value. And that would be sad.
Like staticwave, I want Doit to be successful. More customers bring in more money which means that the company can afford more development. That improves the product. And that is good for all of us.
Regards,
Dan.
Thanks!
-
05/09/2013 01:56#1PRO
-
05/09/2013 03:37#2PRO
Thank you for your feedback.
Previously, we have one, bun unfortunately, he didn't met our requirements. :( We are just looking for someone else that is more professional.
Would you like to help us? Please feel free to let us know if there is any mistake in our app/blog.
-
05/09/2013 17:07#3PRO
Michelle,
I would be happy to help. That said...
I'm probably a typical Doit customer - too many things to do in too little time. I.e. I haven't much spare time. Therefore, I suggest:
- Create a new Blog subject area called something like, "Documentation Changes and Requests". The purpose of the subject area would be to request and suggest changes to any text in your application, web pages, and help documentation.
A separate documentation subject area is very important because it allows your staff and customers to efficiently share information about your documentation. Most importantly, it ensures that documentation discussions do not get lost in the bug reports and feature requests.
- Separate marketing messages from technical documentation - help and tutorials. Both should be clear and concise, but there are significant differences. Marketing messages promote your products' benefits using language that catches the POTENTIAL customer's eye quickly. Obviously the purpose is to get them to buy. OTOH...
Technical documentation is for the CURRENT customer. It's primary purpose it to explain and educate, briefly and concisely. Promotional language in technical documentation can be very distracting and many times can be VERY counter productive. For example, when I'm in a hurry (almost always) to understand a Doit feature, I do NOT want to read that a feature is "cool". Either I already know that or I'll determine whether it's "cool" in the context of my needs. I recommend removing extra words and promotional words.
In general, each tech doc topic (feature, technique, process, etc.) should include: a clear title, a brief paragraph explaining the topic, drawings or images that clarify the topic, an short example of the topic in use, and a step-by-step process to implement the topic.
Is this time consuming and a hassle? Yes, it is. In any language. But it improves the documentation tremendously.
- Get books on technical writing. Ultimately, you will decide what documentation changes get implemented and probably do much of the writing yourself. To help with this, there are several good books on technical writing. If you are interested, I can recommend a few.
One specific suggestion - use bullet lists and number lists appropriately. Bullet lists describe an UNORDERED list of facts. Number lists describe an ORDERED list of facts - typically to explain a process. Using one when the other is more appropriate makes the information difficult to read and leads to confusion. For example...
This page: http://doit.im/features has several ordered lists, but some of them look like an unordered list of features. That is very confusing. If it's a unordered list of features, each feature stands alone. I.e. there is no dependency between their use. If it's an ordered list, there is a precedence dependency between them. With these ordered lists, I'm looking for the precedence dependency. In many cases, I am missing that. Which means that I waste time trying to figure it out. Not good.
As a first step, please implement a separate section of your blog to facilitate documentation discussions.
Regards,
Dan.
p.s. I spent 14 years in marketing and the last 23 years in technology. I've written hundreds of marketing and technical documents. Does that make me an expert? No! But I have some decent knowledge about writing documentation. -
05/10/2013 09:48#4PRO
@Dan_public
Thank you for your detailed description.
We will take your suggetion into the future improvement.
If we have any posts, could you help us proofread them? Could I deirectly conact yoy at dan_public@comcast.net?
-
05/10/2013 15:44#5PRO
This is a private comment.
-
05/11/2013 06:54#6PRO
Thank you for your great support. :)