Mailinglist Archive: opensuse-wiki (174 mails)

< Previous Next >
Re: [opensuse-wiki] Style Guide / Standard Templates
  • From: "Rajko M." <rmatov101@xxxxxxxxxxx>
  • Date: Mon, 28 Dec 2009 20:14:36 -0600
  • Message-id: <200912282014.36636.rmatov101@xxxxxxxxxxx>
On Monday 28 December 2009 07:51:39 Mike Gentry wrote:
Couple of things I'm wondering whether we should standardise or not...

1) File system / filesystem. Probably irrelevant, but it might read nicer
if we pick one and stick with it - and it helps with searches.

I would go with plain English "file system".


2) Linux / Gnu/Linux. Again, probably irrelevant, but has some people up
in arms.

Not really that complicated.
Linux is term that almost everybody is using.

"GNU/Linux" advocates forget that word Linux today means kernel to
relative small group of insiders, but for the world it is a suite of programs,
where GNU project contributions are just part of it.


3) Folder / directory. Less irrelevant. I say always use directory,
personally.

I would extend that to use directory, but if program that you describe uses
name folder then don't create confusion. New users have a lot to learn, and
"distinction" between directory and folder is not the most important. It can
be mentioned that it means the same and what is preferred:
"In a following discussion we will use /directory/ and /folder/
interchangeably. They mean the same."


Finally, should we maybe compile a list of boilerplate templates, and
eventually one of the wiki team can put them somewhere appropriate near
here http://en.opensuse.org/openSUSE:Templates ?

The table that is used on http://en.opensuse.org/ is replaced with plain list
on http://wiki.opensuse.org/openSUSE:Templates . You can see is that better
suited for easy editable list.

For example, I'm using;

{{Warning|Editing partitions can cause permanent data loss, and should
only be attempted once all important data on the entire physical disk is
backed up to another physical disk}}

That would require a family of warning templates.

I vote for that kind of editor/writer aid.
Although after some time there will be more, and eventually we will have a new
problem, how to find appropriate one. Current table is not suitable for that,
but something like plain list:

{{Warn_partitioning}} > Editing partitions can cause permanent data loss ...
((Warn_static}} > Static electricity can damage electronic components
((Warn_root}} > Running program as root can have serious consequences
etc.

or replacement for all specific warnings:

{{Warn_read|Partitioning}} which will print out:
*WARNING* : To avoid problems, please read article [[Partitioning]].

Advantage of plain all capital warning right from the start of line is that it
is lesser intrusive for reading, and in my humble opinion, those that will
ignore bold *WARNING* will ignore any warning :)

I'm happy to see it improved, if anyone has suggestions - but I figure it
makes no sense to keep rewriting these every time we make a new page on
which they're relevant. Sometimes you need a custom one, definitely, but
a lot of them are generic (and sorry if that's been done - I couldn't see
it...)

There was 3-4 of the same kind like the current one, but nothing specialized
for certain purpose, so we deleted them.

There is actually more ways to include messages besides templates.

{{:Help:Warning_partitioning}} will include in your text normal page created
in namespace Help with name Help:Warn_partitioning .
*Note* *the* *difference* :
Normal page is prefixed with colon, and those in Template namespace not.
For normal pages you have to include namespace, for those in Template and Main
namespace not.

Similar function/operation is substitution:
{{subst:Warn_partitioning}}
will include template/article as text, and any subsequent change in template
will not change your text. After saving your text there will be no more
{{subst:Warn_partitioning}} in it, but the same text as in template.

Above is useful if you have instructions for specific procedure, bound to
openSUSE version 11.1, like Partitioning, and you don't want that update of
article Partitioning to fit 11.2 mess your article created for 11.1.

More you can find on:
http://en.wikipedia.org/wiki/Wikipedia:Transclusion

Thanks, Mike.


There is a lot more tools in MediaWiki than we use on a regular basis.
Recent activity to clean up en.o.o forced me to look around and "discover"
some of them.

--
Regards Rajko,

openSUSE Wiki Team: http://en.opensuse.org/Wiki_Team
People of openSUSE: http://en.opensuse.org/People_of_openSUSE/About
--
To unsubscribe, e-mail: opensuse-wiki+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-wiki+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups
References