OpenEuphoria

Re: New Docs Online

• Posted by DanM Jul 26, 2008
• 1336 views

Ok, here's mine:

1. The main title (in large black font),
"1 Euphoria Programming Language v4.0"
doesn't need the "1" in front of it, as it's an overall TITLE, and there's no number "2";

2. The next line,
"1 Euphoria Programming Language v4.0"
doesn't need (shouldn't have) "v4.0" at the end, because that SECTION is about Euphoria in general, not version 4.0 in particular;

3. Overall, from my perspective, it's too busy (ie, too much detail all at once, not enough simplified general categories leading to the details;
here's what I would suggest instead:

first, maybe some of the navigation stuff you have at the top, (though I don't really see its value at all)
then:

<title>Euphoria Programming Language v4.0
<first link> 1 Euphoria Programming Language
<second link> 2 Euphoria Reference Manual
<third link> 3 Mini-Guides
<forth link> 4 Language Reference
<fifth link> 5 Release Notes

each of these links would then jump to the appropriate section, whether it's a separate page or just down lower in the TOC page.

4. The "Language Reference" section is way too busy; I think it should rather look like this, stripped of all sub-sections (not including "notes", and of course, each item listed below would jump to the "Page Contents" section for that item):

4.1 Console
4.2 Data type conversion
4.3 Euphoria Database (EDS)
4.4 Date/Time
4.5 Dynamic Linking to C
4.6 Error Handling
4.7 File System
4.8 Input Routines (note: out of alphabetic order)
4.9 Graphics and Sound
4.10 Graphical Image Routines for DOS
4.11 Locale Routines
4.12 Map (hash table)
4.13 Math
4.14 Memory Management and other Machine Level routines
4.15 DOS low level routines (note: out of alphabetic order)
4.16 DOS low level routines (note: manual error, sb only one?)
4.17 Mouse
4.18 Windows Message Box (note: sb "Message Box (Windows)"?
4.19 Operating System Helpers
4.20 Pretty Printing
4.21 Prime Numbers
4.22 Regular Expressions
4.23 Searching
4.24 Sequence Manipulation
4.25 Sets
4.26 Internet Sockets(note: should be "Sockets (Internet)"?)
4.27 Sorting
4.28 Stack
4.29 Statistics
4.30 Multi-tasking (note: out of alphabetic order)
4.31 Text Manipulation
4.32 Extended Types (note: out of alphabetic order, or "Types (Extended?)
4.33 Unicode
4.34 Unit Testing Framework
4.35 Wildcard Matching

5. Within "Language Reference", clicking on any category, like "4.24 Sequence Manipulation" conveniently jumps to a page which has a nice TOC like layout, with a section titled "Page Contents"; it would, however, be nice and useful if each item listed in that top Page Contents section would have a short description (one line only) after it (like Rob did: "open - open a file or device") .

But in another respect, it's also too busy, with respect to all the sub-outline numbering preceding each individual item. The problem as I'm seeing it has three aspects:

1. the presence of the sub-outline numbering in the first place. I understand the infrequent(?) utility of being able to reference someone to a section by that numbering, but I think the majority of the time people will be searching this section by item name, in which cases the numbering just visually interferes with seeing the item name(I don't mean you can't see the item name at all, just that it's made harder to easily & quickly see);
2. the link "underlining" extends under both the outline numbering and the item name, causing it all to "blur together"; it would seem more easy to see and discern the word naming the item if those two (the outline numbering and the item name) were separated, with an underline under each, rather than one underline under both at the same time. Maybe even get rid of the underlining completely--it's not used in the higher levels of the doc, why here?
3. the outline numbering and an item name are of the same size and weight; it would seem to help if the outline numbering for each item here were somewhat smaller, and the item name were in bold.
   
   Dan M.