Page 1 of 1
| Which manual style do you prefer? 19/01/2012 at 15:29 #27760 | |
Steamer
3985 posts |
At present, there are two styles of manual on the Wiki. One just a long page of text, such as Trent, or sperate pages with a contents page, such as Oxted. Since most of the new Simulations have manuals of the latter format, would there be any objection if older manuals were converted to this format, which in my opinion makes information easier to find and gives a better structure, or do people prefer them left as they are? Also, what is the position of Geoff and the development team on this? If the majority want the change, I'm happy to do the work (which will be half copy-and-pasting, and half gap-filling), however I think such a big change to the Wiki should be a community decision. Please post your comments/feelings on this issue. "Don't stress/ relax/ let life roll off your backs./ Except for death and paying taxes/ everything in life.../ is only for now." (Avenue Q) Log in to reply |
| Re: Which manual style do you prefer? 19/01/2012 at 15:49 #27762 | |
Laryk
56 posts |
I prefer manuals with a contents - I would like to have a "previous" and "next" link though, like the Edinburgh manual. Actually, I think what I would prefer the most in how Wikipedia does it - a contents at the top of the page purely to jump to sections in the page. It saves a lot of time not having to reload. :) Coming back to my second point. The way I see it is this: If you are a beginner you generally want to read the whole manual. The newer style makes it a bit inconvenient to do this, having to back to the index to select the next topic. However, an experienced user may need to use the manual to look up a particular piece of information - making the contents invaluable. A combination of the two would be the best solution, I think. Last edited: 19/01/2012 at 16:05 by Laryk Reason: More stuff Log in to reply The following user said thank you: Steamer |
| Re: Which manual style do you prefer? 19/01/2012 at 15:53 #27763 | |
|
John
884 posts 
|
Quote:just a long page of text [...] makes information easier to find and gives a better structureThis. Log in to reply The following user said thank you: Steamer |
| Re: Which manual style do you prefer? 19/01/2012 at 17:36 #27765 | |
|
ledgero2
93 posts |
the long page of text admittedly makes finding something easier if you are not sure which heading it falls under. but then again it is not as 'tidy' looking as multiple pages. ultimately i guess how much info is going on there....tables and photos galore are more suited to separate pages
Log in to reply The following user said thank you: Steamer |
| Re: Which manual style do you prefer? 19/01/2012 at 17:41 #27766 | |
Peter Bennet
5402 posts
|
I prefer the way I did Edinburgh. Peter I identify as half man half biscuit - crumbs! Log in to reply The following users said thank you: Steamer, Meld |
| Re: Which manual style do you prefer? 19/01/2012 at 22:36 #27773 | |
|
UKTrainMan
1803 posts |
Both have their merits, but I very slightly perfer the original style of one page. Internet browsers, ever since IE, have pretty much always had a search/find feature (usually accessed via Ctrl+F) to find the sought information within the page. Merits of one whole page include making it easier to print it all off in one go, if needed. However, I couldn't see a problem with perhaps a 'combined version' with links at the top to the sections below. Any views and / or opinions expressed by myself are from me personally and do not represent those of any company I either work for or am a consultant for. Log in to reply |
| Re: Which manual style do you prefer? 19/01/2012 at 23:52 #27779 | |
|
maxand
1637 posts |
If it's all on one page, it's a lot easier to search for something, and downloading is a one-step operation instead of having to use an offline browser (aka web spider) such as Teleport Pro to save all pages in one download with relative links preserved. Thus, a single-page manual is far easier to display and search, particularly when one is offline. Conversely, if it's on separate pages, one may have to do a browser search on most of them before finding what you are looking for, or else use the wiki search engine if the manual writer decides to keep the manual online. The wiki search engine may return many more false positives. Just as in other sections of the Wiki, dividing a topic across several subpages may result in the newcomer having no clue as to where to start looking for something without using the Wiki search engine, which is tedious. For example, the titles of the subpages in the User Wiki section aren't IMO sufficiently detailed or intuitive, hence the need for an Index. The paradox is that the more detailed and informative (i.e., useful) a manual becomes, the longer the page if it is a single page. I can see not one but two reasons for dividing a manual across several pages. The first is to create shorter pages for the reader. The second is to make it easier to edit, for the writer. Neither of these reasons is entirely valid. To take the second one first, if DokuWiki (the editor) sees more than two headings in the page, it creates its own Table of Contents on the RH side to make it easier for the editor to jump to the desired section. Additionally, at the bottom RH corner of each section (when editing) is a little Edit button, so one can easily edit that section on a single "page" and not worry about disturbing the other sections. As for reader comfort, the advantage of breaking the manual into sections is offset by the need to create clear links somewhere (e.g., at the bottom, worded "Previous | Contents | Next", and to have to correct each link should a major change occurs, rather than relying on DokuWiki's inbuilt breadcrumbs trail, which may not be as apparent or intuitive to newcomers (what the heck is usertrack?). I'm also against the idea of having two versions of a manual, one broken up into sections and the other a single page, simply because this duplication is difficult to keep in sync. Likewise I'm against the idea of having one version in HTML and another in PDF, for the same reason. My solution is similar to that of UKTrainMan, with nearly everything on one page, the exception being "sidebars" with extra detail and maybe illustrations, such as Hints, Tips, etc, that can be given their own pages without omitting any key search terms from the main page. The Wiki Syntax page states: Quote: linking to a specific section is possible, too. Just add the section name behind a hash character (#) as known from HTML. It's a pity this feature isn't used more in our manuals. I admit I haven't used it much yet, simply because learning to edit in DokuWiki can be a real PIA. However, to get the best of both worlds, it's necessary to come to grips with this beast and create a Contents section with a list of links at the top of the page to sections below that would otherwise each take up their own page in the multi-page alternative referred to above. Additionally, it's highly desirable and considerate to create a "Back to top" link at the bottom of each section instead of expecting the user to scroll or press Ctrl+Home to return. Doing all this makes a single-page manual look professional, easy to search and a pleasure to read. Last edited: 20/01/2012 at 00:12 by maxand Log in to reply The following users said thank you: alan_s, Steamer |
| Re: Which manual style do you prefer? 20/01/2012 at 07:48 #27784 | |
|
alan_s
152 posts |
I prefer having it all on one page for the reasons given above. As Maxand said, you can still have a table of contents and inline anchor points to be able to jump directly to the section you are interested in, if you're not just wanting to read the whole thing. Alan Last edited: 20/01/2012 at 07:50 by alan_s Log in to reply |
| Re: Which manual style do you prefer? 20/01/2012 at 09:06 #27788 | |
GeoffM
6376 posts |
A perfect example of how you can't please all the people all the time! One manual I'm writing at the moment would come to 20+ pages if printed on paper which is far too much - too much on the screen as well. So it's split up into relevant sections: one for each panel/workstation, a timetable section, a signal directory, an introduction/history, etc. The use of "next" and "back" in a Wiki rarely makes sense as you can arrive at a page from numerous sources. SimSig Boss Log in to reply |
| Re: Which manual style do you prefer? 20/01/2012 at 10:32 #27795 | |
|
kbarber
1743 posts |
Personally, where practicable, I like a contents section referring to sections on the same page - in effect a subdivided single page. In the situation Geoff's talking about I imagine it could be envisaged as several large single pages? There do seem to be some natural divisions of the material there - timetable, signal directory, panels/workstations seems logical to me, though of course I don't know what the reality is so it might be quite different - allowing the contents-and-long-page structure within each of those divisions. But that's only one view, and I'm an old dinosaur anyway 
Log in to reply |
| Re: Which manual style do you prefer? 20/01/2012 at 12:52 #27803 | |
|
maxand
1637 posts |
Keith Barber: Quote: In the situation Geoff's talking about I imagine it could be envisaged as several large single pages? There do seem to be some natural divisions of the material there - timetable, signal directory, panels/workstations seems logical to me, though of course I don't know what the reality is so it might be quite different - allowing the contents-and-long-page structure within each of those divisions.I agree with you Keith. When I wrote earlier that I preferred a long single-page manual to one page per section, obviously there's an upper limit to size here, above which one has to use sections. I based these remarks on the manuals I've read, which are for smaller sims. After reading a manual from beginning to end for the first time, the next time we look at it is usually to search for an answer to a problem, if indeed it's even in there. So let's make ease of searching a manual top priority, by putting as much of the difficult stuff that needs to be searched on as few pages as possible, ideally one. Here I mean the "Operating a Simulation" page. The rest of the stuff can go on separate pages, and extra details, examples and illustrations into sidebar pages. The trick may be to write the manual as many small sections, then see how many one can group together on a single page. Last edited: 20/01/2012 at 12:54 by maxand Log in to reply |
| Re: Which manual style do you prefer? 21/01/2012 at 15:50 #27891 | |
|
alan_s
152 posts |
" said:One manual I'm writing at the moment would come to 20+ pages if printed on paper which is far too much - too much on the screen as well. So it's split up into relevant sections: one for each panel/workstation, a timetable section, a signal directory, an introduction/history, etc.But that's the benefit of screens - they are not a fixed size, thats what scroll bars were invented for!! This is exactly the case where in my opinion a single "page" is much better, providing there are inline markers so you can jump to each panel/timetable/etc. You can also do a ctrl-F to search through the entire text in one go when looking for something particular. Alan Log in to reply |
| Re: Which manual style do you prefer? 21/01/2012 at 20:35 #27913 | |
|
GeoffM
6376 posts |
" said:" said:If that scrollbar moves one pixel and jumps a couple of pages then it's not very helpful. Going to have to agree to disagree on this one as there are pros and cons to each approach.One manual I'm writing at the moment would come to 20+ pages if printed on paper which is far too much - too much on the screen as well. So it's split up into relevant sections: one for each panel/workstation, a timetable section, a signal directory, an introduction/history, etc.But that's the benefit of screens - they are not a fixed size, thats what scroll bars were invented for!! This is exactly the case where in my opinion a single "page" is much better, providing there are inline markers so you can jump to each panel/timetable/etc. You can also do a ctrl-F to search through the entire text in one go when looking for something particular. SimSig Boss Log in to reply |