Documentation writer wanted

kichik
11th December 2002 19:44 UTC

Documentation writer wanted
We are looking for someone who wants to improve the NSIS 2 documentation. The current documentation doesn't usually spare a word more than needed and we would like to see that changed. We want to have the documentation more readable, with more explanations, examples, and organization. It would also be nice to have some tutorials for newbies. Who ever takes this job will of course have the help of all of the current project members.

Job requirements:

Good English
Above average knowledge in NSIS
I do not ask here for someone who knows everything about NSIS, just someone who knows a bit more than using SetOutPath, File and sections. Again, whoever takes this job will have the help of current project memebers whenever needed.
Some free time :D

If anyone is interested just reply here (replying to a sticky post is possible) or send me a PM.

Thanks in advance,
The NSIS Team

kichik
16th December 2002 17:05 UTC

Please congratulate the newest addition to the NSIS team, Mottel. Mottel will be writing the documentation for NSIS 2 so we will all be able to understand better and learn faster.

Good luck Mottel! :D

kichik
7th February 2003 13:12 UTC

As it seems, Mottel doesn't have the time for it currently, so I am re-opening this wanted ad. Does anyone want to help us?

Joel
7th February 2003 20:40 UTC

I would like to help, but I need to know
the time that must be ready....I work and study (college student too :))
Or splitting the work maybe a good optional kichik:
1.- One remake the documentation.
2.- One Make the examples
3.- One Tutorials

kichik
7th February 2003 22:26 UTC

Thanks dark_boy. flizebogen has already responded and said he'll do it. Nevertheless, an extra hand is always helpful :D

Please contact him and set between you two who wants to do what. I have e-mailed you his ICQ number.

virtlink
14th February 2003 13:03 UTC

XML Documentation files?
I've contacted flizebogen and he said that an extra hand is always welcome.

Since then, I have been trying to come up with a better system for writing the NSIS documentation than Halibut (which is good, but could be more advanced).
I tought about using XML files for the data and let a XSLT-file do the styling. That can then be compiled by an XSLT-compiler, like the freeware program Saxon.
I have made an example page of the File instruction. The XML file is rather simple, but the stylesheet does the style, so the stylesheet is the complicated thing.
The document now looks like a combination of the Visual Basic helpfiles and the C#.net helpfiles, but this can be changed to anything someone would desire.
I can't post the sample html here now, since I'm not at my own computer, but I will do it in a few days (propably tonight (GMT 11:00), else tomorrow).

Please reply if you like this XML idea or not. KiCHiK told us many times that the documentation should be as easy update-able as possible, and I think that XML is the only solution that doesn't require much work, but is complex enough to provide the nescessary markup.

Sunjammer
14th February 2003 13:27 UTC

I've always liked the XML idea because if structured carefully programs can extract useful information from it directly. The separation of style from content when using XSLT is very useful, and also allows for more than one style should we ever feel the need.

XSLT could also allow for automatically extracting lists of links or a contents page or whatever without explicitly creating one in the XML.

virtlink
14th February 2003 13:34 UTC

Originally posted by Sunjammer
I've always liked the XML idea because if structured carefully programs can extract useful information from it directly.

I never tought of that, but you're right.

Also posted by Sunjammer
The separation of style from content when using XSLT is very useful, and also allows for more than one style should we ever feel the need.

Like the forum, that also allows a Ninja style or a NDSN style.

Also posted by Sunjammer
XSLT could also allow for automatically extracting lists of links or a contents page or whatever without explicitly creating one in the XML.

Another advantage.

But I actually tought that it might not be easy enough, since you still have to work with tags in your text. But most bugs are removed from the Style.xsl that I made, and many functions are available for text formatting, like styles for:
The instruction's name, parameters, switches, syntax lists (lists with information about each part of the syntax of an instruction), syntax, examples, 'see also', notes, remarks. Links are also possible.
I have been learning XSL since yesterday, expecially for this purpose, and I still don't get it all. If anyone knows a very, very good tutorial about XSL or XSLT, then I'd like to hear about it.

Sunjammer
14th February 2003 13:57 UTC

Just search for XSLT guide or XPath guide in google. Don't forget that XPATH is a specification in it's own right (see www.w3c.org) and is heavily used by XSLT.

virtlink
14th February 2003 16:35 UTC

Here is a sample documentation file:
Just open file.xml in IE6 (or another XML capable browser).

Sunjammer
14th February 2003 16:50 UTC

Sweet

virtlink
14th February 2003 19:03 UTC

Add the attached file to the files in the zip above and you'll see another page: Delete instruction.