documentation template / Discussion

This is the discussion related to the wiki page documentation template.

u9 14 May 2007 09:42

Here are some ideas for a few changes to the template.

• "Keyword Name," the first title, should be removed. The name of the keyword will be the title of the page and writing it agian is redundant and actually only makes a double-title, in fact the same title written twice.
• "Example of Use" title follows the "Examples" title without any text. This is also a double-title and is not so good. I think there should always follow text after a title. So i propose we remove the "Example of use" and "specific example" titles when they are not needed.
• The "Versions Supported" section should only contain the first version the keyword was included, or if it is removed again, then it should be in the format "from version -> to version". This makes maintaining the documentation much easier.

hartnell 14 May 2007 10:06

Give me a bit to think about this. I've been using this template for years. :) —hartnell

u9 15 May 2007 22:10

The template is excellent. These are just some minor suggestions for making it easier to maintain and to avoid the double headings.

hartnell 16 May 2007 13:02

I've changed the keyword name.

For the other two, open for discussion (as always) :

Example of Use

This is intended to be a generic example showing what it does, without a specific use.

Versions Supported

The reason I'm so anal about version numbers is because when looking for docs, about 5% search for a version number too. Therefore when that 5% find the page they are looking for, they are still confused if the documentation is "up to date" or supports their version.

-hartnell

u9 19 May 2007 20:16

The problem with the versions is that every time a new version is released (which for b2d is very very often) every single page has to be edited to include the new release. This is a _lot_ of overhead. Most software maintains backward compatibility, therefore it can be assumed that a function in one version will be available in all subsequent versions, and if it is not then it is noted in the docs when it was removed.

hartnell 20 May 2007 02:14

If you mean "wow, that alot of work" by "a_lot_of overhead", don't worry, I'll do it. :) In fact, strangely enough, I like doing it. :) —Zippy the squirrel.

hartnell 22 May 2007 08:37

Ok, I've removed the example of use. :) The only thing we disagree on is the version number, which I'm very anal about. Give me time, I'll probably see you are correct.

— someone-said-something-about-me-signing-my-name-all-the-time
— so-now-i-sign-strange-names-for-fun-this-is-probably-a-phase.

Last edited on 22 May 2007 08:38 by hartnell Show more

New B2D Policy

hartnell 25 May 2007 09:50

I like it. Only two things :

1. Brutus2D in titles :

Sometimes this is necessary because this is a large site covering many different tools. So, "Load and Display an Image" begs the question "Load and Display an Image in What?" This is especially a problem when searching.

2. () in links

Wikidot is an amazing thing. It removes the () if you link it : key.Pressed(). Look at where that actually leads. However, your version LOOKS better so I suggest we do it your way.

key.Pressed()
vs
key.Pressed()

—hartnell

u9 26 May 2007 10:53

About the double headings. What i ment was that it is bad to have a headline where the next line is another headline. There should always follow text after a headline. So if nothing else, then an explanation of what will follow.

B2D in titles: I tried searching and you are right. One cannot select a specific category to search in. This is a bit bad so from that point of view it makes sence to leave in the B2D in the titles. I don't know how successful i would be in finding the same page if b2d wasn't in the title.

() in links: I too think it looks better having the () outside the links. As you say, this is just looks.

There was one other thing, but maybe this is more general for the entire wiki. We should try to minimize the use of italic styling on the site. Italic is very difficult and a bit unconfortable to read on a computer screen. Asking anyone working in publishing they will say that italic on a computer screen is a no-no. One should try to avoid using it. I'm not saying never use it, just minimize it and try avoid using it on entire sections of text. The reason one doesn't use italic on computers is because it becomes so jerky due to the low resolution of the screen. There is a similar problem with serif fonts because they come to seem cluttering on the screen. But we don't have any serif-fonts here soe :)