Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by DanM Aug 05, 2008
- 1246 views
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";
There should be 2, 3, 4 and 5. Soon there will be more.
Sorry, guess I wasn't clear: I'm not talking about the five numbered sections, for which there will be more in the future, ie:
1 Euphoria Programming Language v4.0
2 Euphoria Reference Manual
3 Mini-Guides
4 Language Reference
5 Release Notes
I see them. I'm not referring to the first item in the above list, but rather to the actual main title, the line just under:
Previous Chapter: None Previous: None Up: 1 Euphoria Programming Language v4.0 Next: 1.1 Introduction Next Chapter: 2 Euphoria Reference Manual
that is, the TITLE of the doc; that's the line that doesn't seem to need the "1" in front of it, since there would only be one title for the doc, therefore no need to identify it as list item #1.
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;
The whole document (in which that is the title) is reference for 4.0. As well, the general introduction will be changing to include a short section about all the new things in 4.0. But the 4.0 is needed to distinguish it from 3.x docs.
See above comment: I'm not talking in this instance about the title. Of course you're correct that the title either needs or can very much benefit from indicating that this doc is for v4.0; but that's not the line in the doc I'm referring to, it's the second line which again says
"1 Euphoria Programming Language v4.0"
but in a smaller font, and is (currently) the first section of 5 sections, that I'm suggesting doesn't need the "v4.0" after it; after all, none of the other similarly numbered sections include it. Again, that section is just about Euphoria in general, at least for the most part.
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.
Better navigation is needed. I am not sure how to fit all of that into the docs with out adding to the navigation complications. The navigation has changed since this message was posted. Is this still an issue for you?
I'm not entirely sure. I can't recall if the earlier version of the doc had underlining under all the items on the main page or not; if it did, and you removed them, then that helps, although it's not my main concern on that page. I'd like to see a condensed TOC, where the 5 (or more) main sections are just listed by name/link, so navigation would just be a matter of clicking on the desired section name, and then (specifically for Language Reference), on the desired routine category.
However, if this is very much not what you want for the doc, I wonder if you could let me try to work on a variant of the doc generating program, to see if I could make it output as I'd like? I'd much rather not have to deal with SVN (old dogs not like to have to learn new tricks), and I'd need some version or portion of Euphoria 4.0 to run it against. Of course, if I try to do this, it will take me at least forever and a day! 
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
<snip>
That is the only place where all functions are listed, many people use that page to do a Ctrl+F and start typing the function name they are looking for. That Toc is a section TOC and like any book, it will have much more detail. A technical text book will have a TOC at the front that lists major divisions, then when you go to an individual chapter, they will have a detailed chapter TOC. That is what you see on teach major section (chapter).
Ok, I think I understand, but when I'm looking for a function, it's often the name I can't remember, so I start looking for the general category, and then read down a list of them, so I can recognize it when I see it. Different strokes. 
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") .
Yes, that would be nice, however we must realize that we have went from ~200 total functions to > 500 and by the time it's done I would say we will be over 600 functions. I am not yet sure how all this will work out.
Also, at this point in time it's a limitation of our document generation. When Rob was maintaining it, he had to manually create all TOC's. When he added a new function he had to change all reference numbers everywhere, he had to update index pages, he had to update the overview page, etc... There is no way we can maintain that manually with how rapidly things have been changing. Thus we are now all automated. Now, the problem with the automation is that a section title for book like material such as explaining a For loop is no different than a section title for the function split.
I have some ideas about how this could work, but then their is the idea of getting the short description from the inline docs also, that we moved to. (we maintain docs right with the functions now instead of having a separate place which leads to forgetfulness). The best thing I can come up with is take the short description as the first sentence in the description.
Yes, using the short description that's inline with the function(s) themselves, as the short description in the line with the name of the function in the docs, that's what I mean.
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:
- 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);
Bear in mind the docs will be available in PDF and .txt formats as well. I personally very much like the section numbering. It gives me reference. Most technical manuals (including the 3.x docs) have section numbering.
Well, actually the 3.x docs don't carry the sub-section numbering down to the same degree. 3.x has SECTION numbering, but not sub section numbering. "2.9", but not "2.9.4.1"
I can understand that the sub-section numbering can be useful for referring people to, but just reading the doc, all those numbers tend, for me, to be unnecesarily distractive. It's the names of the routines I'm interested in seeing, not the sub-section numbering. Not asking you to remove them, just maybe make (or wait forever for me to make?) an alternative view that is "condensed". Could have a button at top of TOC that says, "Condensed View of TOC", perhaps?
- 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?
- 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.
Underlining is pretty ugly. I have not styled the TOC sections yet, really. I will remove underlining from the TOC. I will also work further at making it easier to read. It's just not where my focus has been yet.
Understood. And thanks for all your (& all you'se all's) efforts to expand/improve Euphoria
Thank you for your comments. This gives me some action points that I will address.
Jeremy
Dan M.
