On Fri, Dec 03, 2010 at 02:01 PM, Dylan Smith said: > I think the fish user documentation could be improved, but it > certainly follows the law of discovery. You can find all the > help topics but just typing "help".
This is not true. Try for example "help title". It works and takes you to information about the fish_title function but it does not exist in the current TOC. AFAIK, the *only* place the list of topics in $fish_help_topics (in help.fish) exists is in that variable. This list does not occur anywhere else. I think it is a useful list and it should be made known to the users. The other alternative is to just get rid of this list but I think that would be a mistake. > The main reason why the table of contents is so long is that it > includes a table of contents for the commands page. I believe > this should be moved to the commands page, so that they can > click on the commands link at the top of the page to get to it. > Thus each page should have it's own table of contents. Agreed. Still, I think it is better to have "help" give the user a short list that easily fits on one page and has an "index" link that gives the longer index. One simple way to do this in the html is to put the very short list above the current table of contents, although I think it would be much better on a page by itself. It's like having a tree directory structure instead of having all the files in one big directory. IMO, having a simple first page is essential to a friendly UI. Look at Google and Bing where the pressure to clutter their home pages is enormous. They are gateways to the web and a host of services yet they start out with an order of magnitude fewer words than we do. But if there is a lot of resistence to this idea, I will shutup about it. > The links at the top could be shortened by changing: > "Main documentation page" -> "User Documentation" > "Design Documentation" -> "Design" > then we could add in a "Tutorial" link Good idea. > The introduction should target a beginner, so if you think it > should be improved to be a better quick start to learning about > the shell. Fair enough (I'm assuming you mean I should offer improvements for the current introduction). > However, I think you are trying to do too much in one patch. > Make small changes so we can get something committed rather > than trying to rewrite everything in one patch and risk having > everything get rejected. I'm sorry for the continued confusion I'm creating about this. I want to get the new help.fish along with an appropriate help.1 man page and help.fish completion page finished and out the (my) door as phase one of improving the help system. I think we are very close to having this completed. Right now, I'm just waiting for any additional feedback. The second phase would involve all this other stuff, basically the content of the help system. The way I work is that when I'm finishing up one phase or project, I start thinking and talking about the next phase. This has two benefits. First, there is often feedback from understanding the next phase that helps in finalizing the design of the current phase. Second, if there are unknowns involved in the next phase, as I believe there are in figuring out the best way to improve the help content, it helps me a lot to talk about and think about the design, and perhaps even get some consensus, before I start coding (or whatever). Again, I'm sorry for all the confusion I'm causing. Peace, James ------------------------------------------------------------------------------ Increase Visibility of Your 3D Game App & Earn a Chance To Win $500! Tap into the largest installed PC base & get more eyes on your game by optimizing for Intel(R) Graphics Technology. Get started today with the Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs. http://p.sf.net/sfu/intelisp-dev2dev _______________________________________________ Fish-users mailing list Fish-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/fish-users
