[Xenomai] Documentation and WIKI

[Xenomai] Documentation and WIKI

[hauptmech]

I'd like to propose a buffer page between the menu options and non-wiki 
pages. Specifically GIT repositories and Installing. A couple reasons... 
One it's unexpected, as conventionally links to outside pages are marked 
as such in a wiki. Two: a wiki page between the menu and the external 
page allows us to put some summary info to help ease the reader into the 
bigger document and add useful tidbits (like the existance of denx)

Examples of buffer pages are at:
http://www.xenomai.org/index.php/Install_Xenomai
http://www.xenomai.org/index.php/GIT_repositories

Link them in (I don't have permission) if you agree.
> The "getting started" page is unfinished (contains empty paragraphs),
> and outdated (contains dead links and references to things like the
> simulator which is currently not really usable) at the same time. I do
> not believe we have the resources to maintain such a page up-to-date.
I think the getting started page is a nice little introduction. I've had 
a pass at cleaning it up.
  http://www.xenomai.org/index.php/Getting_Started
There's more that could be done but if it looks ok, consider linking to 
it from the menu 'Start here'
> I agree with you, we have some information on the wiki, but it seems
> hard to find, seeing how people are asking again and again the same
> questions about configuring an x86 kernel, which are answered and
> hyperlinked in at least three pages on the web site.
It must mean that people are not seeing it as they navigate. It is a bit 
spread out. And to be honest, 'troubleshooting' is not where I'd go 
looking for configuration info. On the other hand, some people just need 
lots and lots of repetition before it sinks into the skull.

-hauptmech

Re: [Xenomai] Documentation and WIKI

[Gilles Chanteperdrix]

On 12/16/2012 08:20 PM, hauptmech wrote:

> 
> I'd like to propose a buffer page between the menu options and non-wiki 
> pages. Specifically GIT repositories and Installing. A couple reasons... 
> One it's unexpected, as conventionally links to outside pages are marked 
> as such in a wiki. Two: a wiki page between the menu and the external 
> page allows us to put some summary info to help ease the reader into the 
> bigger document and add useful tidbits (like the existance of denx)
> 
> Examples of buffer pages are at:
> http://www.xenomai.org/index.php/Install_Xenomai
> http://www.xenomai.org/index.php/GIT_repositories
> 
> Link them in (I don't have permission) if you agree.
>> The "getting started" page is unfinished (contains empty paragraphs),
>> and outdated (contains dead links and references to things like the
>> simulator which is currently not really usable) at the same time. I do
>> not believe we have the resources to maintain such a page up-to-date.
> I think the getting started page is a nice little introduction. I've had 
> a pass at cleaning it up.
>   http://www.xenomai.org/index.php/Getting_Started
> There's more that could be done but if it looks ok, consider linking to 
> it from the menu 'Start here'


It is sort of a replacement of "Start here", so, from my point of view,
it should be the "Start here" page, and also contain what the "Start
here" page contains (namely, the link to the "porting posix applications
to xenomai", and all the links to all the API documentation versions).

-- 
                                                                Gilles.

Re: [Xenomai] Documentation and WIKI

[hauptmech]

On 12/16/2012 09:19 PM, Gilles Chanteperdrix wrote:
> On 12/16/2012 08:20 PM, hauptmech wrote:
>
>> I'd like to propose a buffer page between the menu options and non-wiki
>> pages. Specifically GIT repositories and Installing. A couple reasons...
>> One it's unexpected, as conventionally links to outside pages are marked
>> as such in a wiki. Two: a wiki page between the menu and the external
>> page allows us to put some summary info to help ease the reader into the
>> bigger document and add useful tidbits (like the existance of denx)
>>
>> Examples of buffer pages are at:
>> http://www.xenomai.org/index.php/Install_Xenomai
>> http://www.xenomai.org/index.php/GIT_repositories
>>
>> Link them in (I don't have permission) if you agree.
>>> The "getting started" page is unfinished (contains empty paragraphs),
>>> and outdated (contains dead links and references to things like the
>>> simulator which is currently not really usable) at the same time. I do
>>> not believe we have the resources to maintain such a page up-to-date.
>> I think the getting started page is a nice little introduction. I've had
>> a pass at cleaning it up.
>>    http://www.xenomai.org/index.php/Getting_Started
>> There's more that could be done but if it looks ok, consider linking to
>> it from the menu 'Start here'
>
> It is sort of a replacement of "Start here", so, from my point of view,
> it should be the "Start here" page, and also contain what the "Start
> here" page contains (namely, the link to the "porting posix applications
> to xenomai", and all the links to all the API documentation versions).
>
I see what you mean. The Documentation Summary (start here) is nicely 
compact, I wouldn't want to ruin it. What about calling 'getting 
started'  'beginners guide' and inserting a link to it between 'Start 
here' and 'Installing'?

Re: [Xenomai] Documentation and WIKI

[Gilles Chanteperdrix]

On 12/16/2012 10:12 PM, hauptmech wrote:

> On 12/16/2012 09:19 PM, Gilles Chanteperdrix wrote:
>> On 12/16/2012 08:20 PM, hauptmech wrote:
>>
>>> I'd like to propose a buffer page between the menu options and non-wiki
>>> pages. Specifically GIT repositories and Installing. A couple reasons...
>>> One it's unexpected, as conventionally links to outside pages are marked
>>> as such in a wiki. Two: a wiki page between the menu and the external
>>> page allows us to put some summary info to help ease the reader into the
>>> bigger document and add useful tidbits (like the existance of denx)
>>>
>>> Examples of buffer pages are at:
>>> http://www.xenomai.org/index.php/Install_Xenomai
>>> http://www.xenomai.org/index.php/GIT_repositories
>>>
>>> Link them in (I don't have permission) if you agree.
>>>> The "getting started" page is unfinished (contains empty paragraphs),
>>>> and outdated (contains dead links and references to things like the
>>>> simulator which is currently not really usable) at the same time. I do
>>>> not believe we have the resources to maintain such a page up-to-date.
>>> I think the getting started page is a nice little introduction. I've had
>>> a pass at cleaning it up.
>>>    http://www.xenomai.org/index.php/Getting_Started
>>> There's more that could be done but if it looks ok, consider linking to
>>> it from the menu 'Start here'
>>
>> It is sort of a replacement of "Start here", so, from my point of view,
>> it should be the "Start here" page, and also contain what the "Start
>> here" page contains (namely, the link to the "porting posix applications
>> to xenomai", and all the links to all the API documentation versions).
>>
> I see what you mean. The Documentation Summary (start here) is nicely 
> compact, I wouldn't want to ruin it. What about calling 'getting 
> started'  'beginners guide' and inserting a link to it between 'Start 
> here' and 'Installing'?
> 


I think the farther the information (in count of navigation hops) is
from the main page, the less it is likely to be found, and this is
verified by the statistics on page accesses.

So, I suggest the "Getting started" guide, or whatever its name should
be directly accessible from the main page.

-- 
                                                                Gilles.

Re: [Xenomai] Documentation and WIKI

[hauptmech]

On 12/16/2012 10:30 PM, Gilles Chanteperdrix wrote:
> On 12/16/2012 10:12 PM, hauptmech wrote:
>
>> On 12/16/2012 09:19 PM, Gilles Chanteperdrix wrote:
>>> On 12/16/2012 08:20 PM, hauptmech wrote:
>>>
>>>> I'd like to propose a buffer page between the menu options and non-wiki
>>>> pages. Specifically GIT repositories and Installing. A couple reasons...
>>>> One it's unexpected, as conventionally links to outside pages are marked
>>>> as such in a wiki. Two: a wiki page between the menu and the external
>>>> page allows us to put some summary info to help ease the reader into the
>>>> bigger document and add useful tidbits (like the existance of denx)
>>>>
>>>> Examples of buffer pages are at:
>>>> http://www.xenomai.org/index.php/Install_Xenomai
>>>> http://www.xenomai.org/index.php/GIT_repositories
>>>>
>>>> Link them in (I don't have permission) if you agree.
>>>>> The "getting started" page is unfinished (contains empty paragraphs),
>>>>> and outdated (contains dead links and references to things like the
>>>>> simulator which is currently not really usable) at the same time. I do
>>>>> not believe we have the resources to maintain such a page up-to-date.
>>>> I think the getting started page is a nice little introduction. I've had
>>>> a pass at cleaning it up.
>>>>     http://www.xenomai.org/index.php/Getting_Started
>>>> There's more that could be done but if it looks ok, consider linking to
>>>> it from the menu 'Start here'
>>> It is sort of a replacement of "Start here", so, from my point of view,
>>> it should be the "Start here" page, and also contain what the "Start
>>> here" page contains (namely, the link to the "porting posix applications
>>> to xenomai", and all the links to all the API documentation versions).
>>>
>> I see what you mean. The Documentation Summary (start here) is nicely
>> compact, I wouldn't want to ruin it. What about calling 'getting
>> started'  'beginners guide' and inserting a link to it between 'Start
>> here' and 'Installing'?
>>
>
> I think the farther the information (in count of navigation hops) is
> from the main page, the less it is likely to be found, and this is
> verified by the statistics on page accesses.
>
> So, I suggest the "Getting started" guide, or whatever its name should
> be directly accessible from the main page.
>
I agree. I meant inserting a left side wiki menu link in the 
documentation section between "Start Here" and "Installing"