Emerald Editor Discussion
May 24, 2017, 04:42:46 pm *
Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
News:
 
   Home   Help Search Login Register  
Pages: [1] 2 3
  Print  
Author Topic: Documentation  (Read 27979 times)
0 Members and 1 Guest are viewing this topic.
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« on: May 11, 2006, 11:20:21 pm »

I think the documentation probably needs to be written along with the program itself - as we write features, we should document it.

As has been noted, CE used plain HTML files in its documentation, and this is a practice I intend to follow. It will end up in the SVN repository under another branch.

As I'm not a fully fledged C/C++ coder yet, I'll make a start with the documentation branch since I can write that!
Logged

"Cleverly disguised as a responsible adult!"
dsvick
Beta Testers
Senior Miner
***
Posts: 52



WWW
« Reply #1 on: May 11, 2006, 11:49:27 pm »

Quote from: Arantor
As I'm not a fully fledged C/C++ coder yet, I'll make a start with the documentation branch since I can write that!
And that was going to be my line  Smiley

I like the idea of the HTML docs too, much easier to write, maintain, and can be viewed and look the same on almost all browsers. IF you set up a basic template and some CSS for it then when the developers and testers start doing their own help, it'll all be consistent and look the same.
Logged

Dave
alpha
Developers
Senior Miner
***
Posts: 78


« Reply #2 on: May 11, 2006, 11:52:55 pm »

There are two kinds of documentation, user documentation and source code documentation. For source code documentation we can use Doxygen or some other tool.
http://en.wikipedia.org/wiki/Doxygen

The user documentation is more complex:
*manual
*online help
*FAQ
*wiki
...
But it should be possible to have just one set of files and generate the different documents.

Markus Schulz
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #3 on: May 12, 2006, 12:11:41 am »

Well, the online help and the manual can be done together as one thing - I've found that the best online help systems I've used are the manuals - provided that liberal, real-world examples are used to show how to tie the software to the real things that users are going to use it for.

I didn't want to produce them in Doxygen and then throw out the files, my plan was to create and maintain a single format, HTML. I'm reasoning thus: anyone who is going to use EE will be doing so on a graphical user interface. Therefore we might as well make use of that GUI and use HTML files to run the documentation since HTML is a naturally crossplatform environment for writing documents. It supports all major formatting needs (including images, lists, preformatted code) and can be styled quickly in CSS, making it ideal for what we want. Plus, hand-maintained code is (much) cleaner than any generated from Doxygen or similar - I can write HTML faster than I can create a document in Word when I'm at work.

The FAQ I was originally planning to maintain on the server & create a FAQ file as a tidied-up HTML dump from that.

A wiki is an option we can look at later, but I don't want to jump on the "me-too" bandwagon with it.
Logged

"Cleverly disguised as a responsible adult!"
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #4 on: May 12, 2006, 01:36:36 am »

Personally, I dont wish to use wiki...
That is just my thought.  I never cared for the wiki system
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #5 on: May 12, 2006, 01:50:10 am »

Wiki has its uses, but I'm not sure here is particularly one of them.

From a technical perspective, adding MediaWiki support is pretty much trivial for me, since I already maintain 2 wikis with it on this server.

Let's see, though. If it turns out that a wiki would be a really, really great idea, then we'll look at it. Otherwise, I forsee our documentation style being more about us documenting what we do and inviting comments here on the forum.
Logged

"Cleverly disguised as a responsible adult!"
Feldon
Gem Cutter
****
Posts: 106


« Reply #6 on: May 12, 2006, 01:46:30 pm »

XML might be more appropriate.  A lot of other pre-existing projects are shifting their manuals and help documentation to XML.  Its more flexible in that it allows the presentation of the documentation to change without a lot of hassle.  For now you can take the XML and present it using XHTML on the website.
Logged
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #7 on: May 12, 2006, 05:14:11 pm »

On documentation, I am not a full fledged web developer, and have little experience with XML.
I am willing to assist here, but depending on how the documentation is presented, I might need assistance at one point in time to clear up questions I have on it..

But again, this is a little in the future.
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
daemon
Developers
Gem Cutter
***
Posts: 107


WWW
« Reply #8 on: May 15, 2006, 03:24:36 am »

Speaking from the point of view from a developer, the most common way to document something is to use Doxygen to document the API and functions. And then use Docbook to create the manual; this allows PDF, HTML, and CHM generation because it's XML transformed by XSLT.
Logged
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #9 on: May 15, 2006, 12:29:47 pm »

Sounds like a plan.

To be honest, I was originally just going to write it in pure HTML because that's the main format I know how to use.

I can't see why we couldn't use Doxygen and Docbook, so I'll look into that shortly (since I think we need to start documenting fairly soon as well as developing)
Logged

"Cleverly disguised as a responsible adult!"
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #10 on: May 19, 2006, 02:08:18 pm »

We could always have the documenation available using OpenOffice...great to port to PDF's, but then I think that is what you are mentioning Docbook...
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
Arantor
Site Administrator
Administrator
Master Jeweller
*****
Posts: 618



« Reply #11 on: May 19, 2006, 06:10:56 pm »

OO.o is nice and flexible, and the PDFs are a nice touch - but only if you use standard fonts, or don't include the fonts with it. I wrote something a bit back, with a strange page layout, and on Windows, the exported PDF was 212KB including images, while on Linux (embedding a font that I had on Linux but not for Windows) it was 1.7MB.

DocBook is probably much better for what we want than OO.o, although flyers and datasheets could be produced using OO.o (much like the Firefox and Thunderbird ones)
Logged

"Cleverly disguised as a responsible adult!"
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #12 on: May 28, 2006, 02:45:15 am »

Can a website using XML be ported to a PDF file?
Just curious, because we can then port every help release to a downloadable PDF file as well...just a thought
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
daemon
Developers
Gem Cutter
***
Posts: 107


WWW
« Reply #13 on: May 28, 2006, 06:09:47 am »

Yes, using Docbook, you can use XSLT to transform into PDF.
Logged
Zhrakkan
Official Mascot!
Beta Testers
Gem Cutter
***
Posts: 177



WWW
« Reply #14 on: May 28, 2006, 02:15:46 pm »

Great, many people would love to have a PDF of it as well...
Logged

News Manager and Unofficial Mascot
Join the Emerald Editor Project - Message Me!
Emerald Editor - "A Jewel of an Editor"
-----by the way, that name is pronounced "Za-Rack-In"
Pages: [1] 2 3
  Print  
 
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.19 | SMF © 2013, Simple Machines Valid XHTML 1.0! Valid CSS!
Page created in 0.136 seconds with 18 queries.