Products

Solutions

Resources

Partners

Community

Blog

About

QA

Ideas Test

New Community Website

Ordinarily, you'd be at the right spot, but we've recently launched a brand new community website... For the community, by the community.

Yay... Take Me to the Community!

Welcome to the DNN Community Forums, your preferred source of online community support for all things related to DNN.
In order to participate you must be a registered DNNizen

HomeHomeOur CommunityOur CommunityGeneral Discuss...General Discuss...To developers: PLEASE add readme.txt or some quick docs in what ever you releaseTo developers: PLEASE add readme.txt or some quick docs in what ever you release
Previous
 
Next
New Post
5/5/2010 7:46 PM
 
I download lots of software and, man, some of them are just really frustrating. There's 0 documentation on how to install or use the software and I have to spend tons of time Googling and reading lots of text.

Unless your software is an .exe or an .msi which creates a ready to use program out of the box, PLEASE PLEASE
spend a few minutes typing a quick docs file and include it in your archive file. A file like readme.txt. If anything, put your url in that file so in the future I can know where to to go to look for more information. I have some modules and I have no idea where I got them from. I have to dig for keywords from the files  and Google them. In your site PLEASE include some quick start or quick installation docs. It doesn't have to be pretty or have any formatting. Just whip one up quickly.

It seems developers just zip their folders or create a module without any documentation. if you are a developer and you spent tens of hours developing a module, why can't you spend like 15 minutes typing something up and include it in your zip file!? Open up an editor and just type and type. if you're too busy, forget about cleaning it up. It seems this what discourages developers from producing any kinds of docs.

If your module expects free form text (not a checkbox or radio button or a dropdown list) from the user in your settings, you should provide examples of what the field is expecting. If I enter something that didn't validate or is in wrong format, don't just say it's bad data or it's wrong. Tell me exactly why it's bad and what you are expecting. Don't throw an exception at my face. Make your error message as clear as possible. I don't care if they are too verbose. Don't make me think.

It seems a lot of developers think the whole world are developers like them and we can read their minds and understand their apps by just looking at them. Put yourself in the shoes of a non technical user and pretend you know nothing about the app infront of you. if anything might look confusing or not clear to the user, you should add tips, hints, examples & help sections. if you're putting a "?" icon next to a field, don't repeat what the label says. Bring up a tip window which clearly explains what it is and what it's NOT and show some examples.
If you are creating a free module and don't want to invest time in this, again, just put everything in a text file and just type what's in your mind. You will be helping everyone including yourself by not getting support  issues by email, forums and by not frustrating prospective customers.




 
New Post
5/6/2010 2:37 PM
 
This is a good recommendation, however, a readme.txt file still requires that the user go out to the file system in DNN.

My personal recommendation is one of two things.

1.) Add an action menu item to link the users to the developers website
2.) Add help text to the settings control that provides information about the module and vendor.

If you are working with a 5.x manifest there is also the owner information that would be there as well and should be filled out, if using a 5.x manifest

-Mitchel Sellers
Microsoft MVP, ASPInsider, DNN MVP
CEO/Director of Development - IowaComputerGurus Inc.
LinkedIn Profile

Visit mitchelsellers.com for my mostly DNN Blog and support forum.

Visit IowaComputerGurus.com for free DNN Modules, DNN Performance Tips, DNN Consulting Quotes, and DNN Technical Support Services
 
New Post
5/7/2010 12:38 PM
 
When I download module, it's in a zip file. I expect some kind of quick docs in the zip file. It's for human consumption, not for DNN use and not part of the manifest.
 
New Post
5/9/2010 1:44 AM
 
Mitchel raises some good points, however, the main problem with the DNN 5 manifest is that you can't bundle a package for dnn 4 and dnn 5.  So if you want backwards compatibiltiy, you have to offer two separate packages, which confuses people a lot more (which package shoudl I download - I don't know what version I have, my web guy set it up for me, etc).  Either that, or if someone asks for an update, you have to have some back and forth conversation about which version (log on, lookin your host settings, etc) before you can send the file.

My suggestion has always been to allow for an (optional) .dn5 extension for the dnn 5 manifest page.  It's a simple fix and would allow dual-packaging of dnn4 and dnn5 manifests in a single, distributable package.

For the OP my modules always have a separate, downloadable zip file with a full set of html instructions, and I always try and fill in every field with some meaningful help (not 'enter name here' for 'name' field).  And I include a link to the support forum within the module.  There's always more you can do, though.

Personally, I don't include anything in the module zip file because the vast majority of people don't look in the zip file, and just install it - that's been my experience after hundreds of conversations with customers about finding information.

FWIW I also think there should be a move towards allowing module installations to create default pages in the site - ie install a blog module, have a page called 'blog' created with the blog module on it.  There could be a 'don't create default page' option in the installer if you don't want to do this.
 
New Post
5/10/2010 2:46 PM
 
Use long file names to your advantage. How about something like: MyFormModule_for_DNN5_only.zip? If you want to go crazy do this: MyFormModule_for_DNN5_only (use file MyFormModule_for_versions_below DNN5_only.zip).zip. I bet no one will be confused then, will they? And it never hurts to do something like that.  I am surprised a lot of people still try to cram file names into 8 characters only. We left Win3.1 very long time!

As for putting docs inside the zip file. It should be a good practice specially when no docs are available on the website either. What if I am on the plane in a long flight with no web access? An included documentation, which most people don't like to read, would help people with the software AND help kill boring time during the flight!
Personally it annoys me when a software's help is an online version *only*. Not a good idea. At least do it like Visual Studio where you give the option of one or the other or both.
 
Previous
 
Next
HomeHomeOur CommunityOur CommunityGeneral Discuss...General Discuss...To developers: PLEASE add readme.txt or some quick docs in what ever you releaseTo developers: PLEASE add readme.txt or some quick docs in what ever you release


These Forums are dedicated to discussion of DNN Platform and Evoq Solutions.

For the benefit of the community and to protect the integrity of the ecosystem, please observe the following posting guidelines:

  1. No Advertising. This includes promotion of commercial and non-commercial products or services which are not directly related to DNN.
  2. No vendor trolling / poaching. If someone posts about a vendor issue, allow the vendor or other customers to respond. Any post that looks like trolling / poaching will be removed.
  3. Discussion or promotion of DNN Platform product releases under a different brand name are strictly prohibited.
  4. No Flaming or Trolling.
  5. No Profanity, Racism, or Prejudice.
  6. Site Moderators have the final word on approving / removing a thread or post or comment.
  7. English language posting only, please.
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out