FAQ  •  Register  •  Login

A skeleton for the docs; contents hierarchy

<<

programandala.net

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Sun May 23, 2010 9:23 am

A skeleton for the docs; contents hierarchy

I suggest to use the FreeBASIC docs as a guide, especially the FreeBASIC Table of Contents. What do you think?

By the way, I see a problem about FreeBASIC wiki: it lacks page hierarchy, it doesn't show a breadcrumb on the top, what is very important to see where we are in the page tree. Many wikis lack that feature. Some of them use the raw page name (e.g. "main.reference.functions" would be a deeper level than "main.reference"); others use page metadata to configure the hierarchy (what is more flexible because page names can change without changing the structure).

Another possible model is the PHP documentation (see an example of PHP doc page): description, parameters, return values, examples, see also, user contributions...
<<

boriel

Site Admin

Posts: 1462

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Sun May 23, 2010 10:57 am

Re: A skeleton for the docs; contents hierarchy

programandala.net wrote:I suggest to use the FreeBASIC docs as a guide, especially the FreeBASIC Table of Contents. What do you think?

That was (more or less) what I was doing in the main ZX Basic doc page: http://www.zxbasic.net (this is just an alias).
BTW, if someone enters documentation in the wiki, *remember* you must use ZX_BASIC: prefix as name space (just see your brower URL location when reading any ZX Basic wiki article).

programandala.net wrote:By the way, I see a problem about FreeBASIC wiki: it lacks page hierarchy, it doesn't show a breadcrumb on the top, what is very important to see where we are in the page tree. Many wikis lack that feature. Some of them use the raw page name (e.g. "main.reference.functions" would be a deeper level than "main.reference"); others use page metadata to configure the hierarchy (what is more flexible because page names can change without changing the structure).

Another possible model is the PHP documentation (see an example of PHP doc page): description, parameters, return values, examples, see also, user contributions...


The main problem with FreeBasic Wiki, ZX Basic one and most of the others is they lack a "navigation" template. I know how to make a basic template, but not a useful one, with mediaWiki. Still studying it. :roll: Because there are very useful pages, such us a categories one:
http://www.boriel.com/wiki/en/index.php ... Categories or even better, a hierarchical tree of related pages (I think there's a MediaWiki plugin for it).

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest

cron
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by Vjacheslav Trushkin for Free Forums/DivisionCore.

phpBB SEO