Post Reply 
newRPL: [UPDATED April 27-2017] Firmware for testing available for download
04-14-2017, 02:27 AM
Post: #619
RE: newRPL: [UPDATED February 21-2017] Firmware for testing available for download
I like that there's 3 people talking about docs! So far it's been just me and I hate docs.
I'm ready to support *any* community effort to create docs. If you want a wiki, I'll set up a wiki server, if you prefer a different CMS just let me know (as long as it's free and open source, I can install it on my hosting account and get it running for the community).
The website uses Joomla, which is a great CMS but not very good for structured templates, and the articles are stored in a database, so it's not exactly easy to extract them to put in a book if anyone would want one.
Nowadays there's web editors that don't require you to know HTML (Joomla has one included).

There's many options out there, some were mentioned, some were not. An important one is Doxygen, which allows the person that's coding a new command to write structured documentation directly into the source code. It's great because you can keep the docs close to the code, therefore it's easy to keep it updated. However, the output is not very nice and it bloats the source code with entire chapters of text. But it's a valid option.
A wiki is a good option if it can be made secure enough, if it's too open it becomes the target of spam.
There's other CMS systems besides Joomla, but they are all very similar.
Then there's authoring tools: LaTEX is great for book-quality and to keep the format very rigid, but the learning curve will scare contributors away easily. Also, it's not as easy to put the content online as it is with content already in HTML.
The plain text is acceptable as long as the structure is rigid and well defined (rigid as in "I can code a program that scans it and converts to HTML for a website").

Then there's also the on-calc help for each command that is in plain RPL files (plain text). This can be used as a starting point for the command reference, adding more detailed explanations, examples, etc. to the terse 2-line explanation given in the help.
In the meanwhile, I added the ability to take screenshots to the simulator, just choosing an option in the menu will dump the screen as a PNG or any other supported file type. That should help in capturing images for the docs.
Find all posts by this user
Quote this message in a reply
Post Reply 


Messages In This Thread
RE: newRPL: [UPDATED February 21-2017] Firmware for testing available for download - Claudio L. - 04-14-2017 02:27 AM



User(s) browsing this thread: 5 Guest(s)