On Fri, Dec 3, 2010 at 3:03 PM, 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. > > Good point. It appears as if the problem is that "Programmable title" is a subsection of the "Other Features" section. If any of these topics are important to list, then they could be a part of the table of contents, or we should make sure the section title provides some indication of the contents. > > 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. > > I definitely agree with having a tree/hierarchical structure to the help, and with splitting information onto separate pages. That is why I was suggesting to have the table of contents for the commands on the Commands page. Using Google as an example isn't really appropriate here, because their home page is more like our prompt. It is where actions are taken (i.e. search). Also searching for information is more like using (help $topic) than (help). > > > 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). > Yes. The documentation should start with a good overview aimed at beginners, and links for non-beginners to quickly find reference information by topic. > 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). > > That's fine. It just should be a topic for a separate thread/conversation. One conversation is about the patch to help.fish, and the other is about updating the content of the documentation (html or man files).
------------------------------------------------------------------------------ Oracle to DB2 Conversion Guide: Compatibility Made Easier than Ever Before New IBM DB2 features make compatibility easy. In this guide, you'll learn about native support for PL/SQL, new data types, scalar functions, improved concurrency, built-in packages, OCI, SQL*Plus, data movement tools, best
_______________________________________________ Fish-users mailing list Fish-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/fish-users
