Need some advice as we move to 1.0 (Documentation Bugs and Problems)

by Jim ⌂ @, Russell, KY, Sunday, November 25, 2012, 19:19 (2182 days ago)

Hey everybody, I need some help and advice.

The database stuff has gone through a major update and hopefully has been debugged as of I will be using it in one of my classes with a room full of beta testers over the next few weeks.

The on-line documentation has been mostly (not completely) updated for all of the recent changes (including freefile, freenet, freedb, dbnull, ++, --, +=, ...). The EN pages on are the only ones being currently maintained.

We NEED help cleaning up the docs, adding examples to many statements, and working on the existing translations. Email me you "wiki" login and I will add you to the editors group. PLEASE...

The move to the WIKI a couple of years ago has allowed the documentation to stay more up to date and more of us to be involved in that part of the project.

Currently there is a BASIC256 program that will take the WIKI entries and make simple HTML pages that we are including as "off-line" help. This is a tedious process that does not happen very often, so that the off-line help is always out of date. Another issue is that each new revision of docuwiki that comes out includes new formatting and plugin features. Each time a new feature is used it must be manually programmed into the converter.

Is the off-line help important to keep or can we remove it from 1.0? If we do keep it, how do we maintain it?

Need some advice as we move to 1.0

by M Santos, Saturday, December 01, 2012, 10:34 (2176 days ago) @ Jim

I have started the Portuguese translation and, although I´m enjoying it, I can say that there is a lot of repetitive translations and cut and paste processes, so I hope I can find some help.

In relation to the “off-line” help it seems to me that it can be discontinued as there is no point in wasting time with a tedious process that has little advantage. Almost everyone can assess the online help.


Need some advice as we move to 1.0

by Jim ⌂ @, Russell, KY, Monday, December 03, 2012, 04:07 (2174 days ago) @ M Santos

The day-to-day maintenance of the off-line docs was the problem. The previous system required me to download the WIKI internal files and then convert them to HTML using a little (actually big) BASIC256 program. It was only about 95% successful in creating clean and well formatted documents.

Over the last week, I have created a "sh" script using wget and sed that will create a clean and nice off-line copy of the wiki documentation. I am in the final process of testing it to make sure it is doing what we need. It takes quite some time to run but it can be started at off hours and it will update the changes in the documentation automatically (to be committed later).

I should be releasing an install with the new docs in the next week or so.

For all of you (Manuel not included as you are working hard on the PT translation) please help us to maintain the wiki documentation, in your languages. Even the EN stuff needs some work,.


Need some advice as we move to 1.0

by M Santos, Monday, December 03, 2012, 22:51 (2174 days ago) @ Jim

I'm glad you managed make a Wiki-to-HTML program. To be honest I’m not a programmer and I though one could just get something out of the shelf to do that. In relation to the content of the documentation I'm trying to use a less formal, academic , and more children friendly style in the Portuguese translation. I'm not going touch the English version, it is not my native tongue and I make enough spelling mistakes in Portuguese, but I will add any appropriate sample code I produce for the Portuguese documentation.


Need some advice as we move to 1.0

by Jim ⌂ @, Russell, KY, Tuesday, December 04, 2012, 04:45 (2173 days ago) @ M Santos

That will be wonderful. Thanks.

RSS Feed of thread
powered by my little forum