On Sat, Dec 4, 2010 at 4:03 AM, James Bowlin <bow...@mindspring.com> wrote: > 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. >
If I follow your threads correctly, I think we have some misunderstanding here. For clarification, I will use the phrase help-term and help-web. help-term is used to display help content in terminal(in man format or whatever), while help-web is used to show help in a working web browser. (we have to guarantee the browser is "working" but that will be a different story.) So let's began. IMHO(purely my personal opinion), help-term without an argument is good to display the top topics because tons of pages of man will get me headache. However, help-web is OK to display all the contents in a whole. Just because in a web browser, it's easy to search and explore. Dylan's suggestion below is good. But I am OK with current html structure(it saves me some click after all) The feeling of good or bad here is very personal. So it's just a suggestion. >> 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. > Don't hurry. I think this change on help is a big thing. It's worth to consider twice before actual action. -- Cheers, Grissiom ------------------------------------------------------------------------------ What happens now with your Lotus Notes apps - do you make another costly upgrade, or settle for being marooned without product support? Time to move off Lotus Notes and onto the cloud with Force.com, apps are easier to build, use, and manage than apps on traditional platforms. Sign up for the Lotus Notes Migration Kit to learn more. http://p.sf.net/sfu/salesforce-d2d _______________________________________________ Fish-users mailing list Fish-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/fish-users
