#508 reorganize the docs and wiki

open
nobody
None
5
2011-05-04
2011-05-04
Jim Michaels
No

There are 2 issues here that are kind of related.
1. merging the NSIS projects/libraries and wiki docs into the NSIS installer package
2. categorizing the libraries in their own category, and categorizing ALL the built-in NSIS functions (as part of the Scripting Reference, not just the few that are categorized now)

I can't find things I need in the documentation. that's the biggest problem with NSIS.
NSIS is also effectively broken up into 1000 little libraries all over the net.
I say, merge all the docs and files from all the projects into one big installer and release that.
I don't like dealing with piecemeal software. If I want to find something, I will use the search button on help, maybe use a web page search.
tree-based menus are effective for help, but breadcrumb menu systems reduce navigation HTML file size (which speeds page loading for dialup users - useful even if you choose not to make a big installer) - you just have to think hard and to organize things in an intuitive manner.

ISSUE #1
--------
I am tired of piecing together NSIS every time a new release comes out because it wipes out my NSIS include directory.
actually, I think a lot of people would be helped trmendously if more attention were paid on the documentation, so that we can actually find what we are looking for.
I can't find what I am looking for in the documentation. that's every user's biggest complaint with NSIS - I've seen it everywhere on the net. NSIS is broken up into 1000 little libraries all over the net.
I say, merge all the docs and files into one big installer and release that. If I want to find something, I will use the search button on help or I will use google, but I should have to use google only.
I am tired of piecing together NSIS every time a new release comes out because it wipes out my NSIS include directory.

ISSUE #2
--------
The learning process is like climbing an insurmountable mountain rather than a breeze. But somehow, a number of other people on the web have managed to climb, and wrote something with NSIS, and you have to climb on their backs to get your work done.
People aren't always going to be that forgiving. If it's going to be that hard, they will move on to something easier to use and more clear.

1.I think a lot of people would be greatly helped if .
Currently, there is no web navigation to any library or function docs. the help file has a small set of functions categorized, but not the full set. this makes NSIS unusable to developers who wish to use NSIS and turns them away to other installers, believe me.
2. it should be easy to use the reference for any programmer. it should not be the case that "I know what I needed in the language only because I helped write it", but "I know what I needed in the language because I found the functions I needed in 5 seconds in the manuals or on the web".
use categories that are intuitive for everybody. put some thought into it. If you have to, be descriptive, and concise. too-many-words-wide make a web page un-navigable, especially if they are non-breaking spaces. I only use non-breaking spaces.
3. categorized tree-structured (help) or breadcrumb menu (web) access to NSIS functions and libraries, such as "string manuipulation", "processes", "environment variables", etc. and categorize ALL the NSIS functions. This would make NSIS extremely usable.
for the web, use a breadcrumb menu system. an example of one can be found in O'Reilly's CSS Cookbook (it works with search engines because it uses <li> tags).
I usually know basically I want. sometimes I know exactly what I want, so instead of using the tree I go straight to the index. I may also be nicely surprised by some new details, so links to "related" functions are helpful.
4. I want to know what header file I need to include to get whatever function has such and such, or be able to click on a link to get the web page or file/files necessary for the plugin. actually I would prefer to not have to download anything except NSIS, and I don't mind a big download.
- pretty much everybody has broadband. Should you cater to dialup users? I don't know. they have problems downloading 1MB because it takes an hour (plus there's connection drops).

I will bet you take 70-90% of your bug reports on issues such as somebody wanting a feature that's already there or using a feature wrong, only to find out it was in the documentation - ahh, but WHERE in the documentation (how do you find it?)? and what web page? If it's in the built-in docs, great. It's great if you already know the language because you have used it for 10 years, but not for us users.
I can browse the entire docset and look it up if I don't know what I am looking for - ack!
You see, that's the problem. nothing much is categorized. If it was, there would probably be a lot more people using NSIS, and a lot more people considering NSIS as a solution (It might take some time to get your reputation back though).

I am saying that NSIS developers need to regroup and spend some major quality time on the docs and hold off on everything else for a while, making some sort of good reference system (help and wiki). after that re-release, I
think a lot of your bug reports will fade away if you do this right.

If you have 700 wiki pages (like my web site has 700 html pages), a tree menu navigation alone in <li>+<a> tags would produce 120KB worth of content on every page - huge and slow to download.
It did on my site, so I had to find a different navigation system. I found that the breadcrumb menu system which is outlined in the O'Reilly CSS Cookbook to be very effective in warding off page size and helping to organize pages, and making the pages indexable by search engines also.
I had already organized my site into a tree structure - I just had to reorganize for the breadcrumb menu system. and I broke it down into groups.
The breadcrumb menu system was the same one dmoz.org and yahoo somethingorother uses, a breadcrumb menu system. see my site http://JesusnJim.com and browse around for a sample of a breadcrumb menu system. I have about 700 pages, and the pages load really fast.
I also have a menu management system I use to upload the pages that stores the menu structure in an XML file locally and generates the menus and ftp's the files to the server. it could be adapted to work with your setup. it's for PHP and it runs from the commandline on windows. this package is at
http://JesusnJim.com/code/php/menu.html and I just released a new version.

HOW THINGS STAND NOW:
- right now, the wiki as it stands, HAS NO NAVIGATION. I have to use google to find something. and if I don't know exactly what I am looking for, I am out of luck.

- the examples in the documentation are not always helpful/useful or explanatory of how to use the function. The PHP language's enhanced .chm and web documentation uses a really good method for making documentation: code snippets can be contributed to the documentation and appended to a long list in a "grey" section, whereas the rest of the documentation is a white background. and so many of the examples people contribute are most excellent and quite varied and apply to many disciplines, so you are sure to find something you need. maybe they are chosen or something I don't know how they are contributed. maybe each function page is a wiki.
A good example can save you a large number of bug reports and tech support and man hours all around.

- the file examples that come with NSIS are so simple that they are entirely useless for showing how to develop a real, solid installer *template* that changes often (so you should use !defines for things like the program title, program name, version numbers, and some dependencies like the java executables and .net executables that need to be installed), and have .net detection, java version detection, x64 handling, windows version detection and handling for installing the .net versions, and GOOD code for shortcuts that includes a default directory, MUI2, and a license, proper language handling, and section groups, and executable's shortcuts should have a default directory on each (a 32-bit directory and a 64-bit directory). in other words, something real-world and useful.
include a couple of really good ones that are different.

Discussion

  • Anders
    Anders
    2011-05-04

    The wiki is just that, a WIKI. Even if we wanted to merge everything on the wiki into the local install, we can't; Not everything on the wiki is under the same license!

    "the wiki as it stands, HAS NO NAVIGATION" Click Developer Center on the navigation bar...

    And if you have any other issues with the wiki, well, it is a wiki after all, so all you have to do is edit it!

     
  • Jim Michaels
    Jim Michaels
    2011-05-07

    it is still possible to make a set of web pages that are breadcrumb menus for the various categories. it doesn't take an awful lot of them, only one page per category (an index.html page). you can simply use the navigation to access the library stuff as a menu link. it takes up hardly any room on the server. you would need an index.html though.

    or you can code the breadcrumb menu system yourself. a tree menu gets too big for the web. I could do it probably in a couple of days if I had access to the server and I knew what area I could use. unless this is a wiki-only server (ugh).

    If you have a list of wiki page addresses and titles, I can make up a menu system you can execute against your web server based on XML for storage of the structure and a config7.php file to customize it to your site. it just requires some configuring and a little knowledge of PHP (more HTML than PHP).

    doesn't your wiki system have some way of making navigation? Or did it get too massive?
    see http://JesusnJim.com for an example of how to layout such a thing. it's totally HTML+CSS, really no javascript it required (but I put some in for those who wished to turn off the menu for viewing wide pages).

     
  • Jim Michaels
    Jim Michaels
    2011-05-08

    I just had an idea. If you have a main wiki page, you can use links to simulate a breadcrumb menu at the lower part of a page, and at the upper part of a page you can put the category depth. you are welcome to use my pointing arrow image in your wiki.

    or, you can use in place of an arrow a space, --> and a space.
    example of a page:
    Documentation -> string handling
    ----------------------------------------------
    link-to-StrCmp link-to-StrLoc link-to-StrLen, String Handling Libraries: link-to-blah1, link-to-blah2, link-to-blah3, link-to-blah4
    ---------------------------------------------
    StrCmp does blah blah
    ...
    StrLoc Does Blah Blah
    ...
    StrLen does BlahBlah
    ...
    ---------------------------------------------