Kiama Documentation
Seyed H. HAERI (Hossein)
Seyed H. HAERI (Hossein)
Research Assistant
Institute for Software Systems (STS)
Technical University of Hamburg (TUHH)
Hamburg, Germany
ACCU - Professionalism in programming - http://www.accu.org/
--------------------------------------------------------------------------------------------------------------
Tony Sloane
Can I possibly ask each page in the Kiama documentation to have a Next/Previous link? It would also be nice if the TOC becomes numbered with the section numbers observed on the individual pages. I'm afraid every time I want to follow my casual read over the documentation I feel lost.
Seyed H. HAERI (Hossein)
> Having said that, it *is* a wiki, so it's not necessarily intended for linear reading.
Wish you had a good tutorial then...
> The documentation page
>
> http://code.google.com/p/kiama/wiki/Documentation
>
> provides an overview so you can keep track of which pages you have read and which you haven't.
In fact, as a casual reader, here is a part of the problem; Consider
me having left a read page P open on my browser for later follow-up.
When I come back to P, I need to go back to TOC whilst I'm not sure
where from I got to P. In other words, I don't know where to follow
things from. Was every page/section numbered, I could know upon
following links whether I'm jumping elsewhere or not. Augmented with
the Next/Prev bottoms then, I could simply trace my jumps back to
where I should finally hit Next/Prev.
Hope this explains my situation. Sorry if this is too taxing. Soon I
will become a serious reader -- as opposed to a casual one. :)
Tony Sloane
>> Having said that, it *is* a wiki, so it's not necessarily intended for linear reading.
>
> Wish you had a good tutorial then...
Well we have limited time for writing comprehensive tutorials. Much
of the wiki is tutorial in nature already and we improve as we can,
but resources are limited, unfortunately. On the wiki we also publish
research papers and slides/videos of talks which can be useful
augmentation for the wiki pages themselves.
>> The documentation page
>>
>> http://code.google.com/p/kiama/wiki/Documentation
>>
>> provides an overview so you can keep track of which pages you have read and which you haven't.
>
> In fact, as a casual reader, here is a part of the problem; Consider
> me having left a read page P open on my browser for later follow-up.
> When I come back to P, I need to go back to TOC whilst I'm not sure
> where from I got to P. In other words, I don't know where to follow
> things from. Was every page/section numbered, I could know upon
> following links whether I'm jumping elsewhere or not. Augmented with
> the Next/Prev bottoms then, I could simply trace my jumps back to
> where I should finally hit Next/Prev.
>
> Hope this explains my situation. Sorry if this is too taxing. Soon I
> will become a serious reader -- as opposed to a casual one. :)
It's clear what you desire, but the main point is that the path you
take to some part of the wiki is not necessarily the path that someone
else would take. I take your point that more navigation will help and
we will add some, but there is no way we can anticipate in all cases
how you read the docs. As I said, it's not intended to be read linearly
since it's a wiki.
cheers,
Tony