Topic: Documentation (docbook) writers wanted
Documentation (docbook) writers wanted
As you can see, we are working on the new Documentation page and the way I have decided that we should do this is by introducing a dedicated documentation system for generating documentation in different formats (HTML and PDF for starters).
I have done an initial evaluation of Open Source documentation tools and found that docbook was very good and sufficient for our needs. I have done a quick outline for our documentation file:
We have some old documentation lying around which we need to incorporate but most of it probably have to be re-written to fit the new document composition and improvements/changes to the application itself. Here are the old documentation articles:
Anyone interested in working with the DataCleaner documentation? I can do it myself but that will take time away from development tasks which is the bottleneck for releasing DataCleaner 1.5 right at the moment and I really would like to get to a release soon :)
I have done an initial evaluation of Open Source documentation tools and found that docbook was very good and sufficient for our needs. I have done a quick outline for our documentation file:
We have some old documentation lying around which we need to incorporate but most of it probably have to be re-written to fit the new document composition and improvements/changes to the application itself. Here are the old documentation articles:
- the old user guide is the main piece of existing documentatoin.
- the old design docs has most of what should be in the "developers guide" chapter.
- ... and the old features page also contains some database compliancy information.
Anyone interested in working with the DataCleaner documentation? I can do it myself but that will take time away from development tasks which is the bottleneck for releasing DataCleaner 1.5 right at the moment and I really would like to get to a release soon :)
I am interested in helping with the documentation. Please feel free to contact me.
Hi rdbrinkhurst,
Great news. Have you got any experience in making docbook documents?
Maybe you can start off by improving the current document (in the link above) with some nicer formatting? I personally like the spring frameworks' documentation which has a nice header with links to the website and so on. I can provide you with commit access to the documentation.xml file if you know how to use SVN, or you can just send in the file(s) via email?
Great news. Have you got any experience in making docbook documents?
Maybe you can start off by improving the current document (in the link above) with some nicer formatting? I personally like the spring frameworks' documentation which has a nice header with links to the website and so on. I can provide you with commit access to the documentation.xml file if you know how to use SVN, or you can just send in the file(s) via email?
I've just added a few sections to the documentation about Optimization techniques in DataCleaner. This was a pretty technical section so I figured that I was probably the only one who had investigated the subject thoroughly enough to write it by now.
I've set up a script to automatically generate the documentation based on the SVN trunk to this URL:
This of course also means that the docs at the URL is work-in-progress, but it's useful if you want to see the what it looks like as of now.
This of course also means that the docs at the URL is work-in-progress, but it's useful if you want to see the what it looks like as of now.
hello kas
Is datacleaner can be worked as fully command line execution. If user inputs file as a command line for data cleaning and pass the parameters for which data cleaning needs to be done and which tasks of the cleaning such as parsing or standardization etc...and after that run it and gets an output file. Is it possible with DataCleaner.
Is datacleaner can be worked as fully command line execution. If user inputs file as a command line for data cleaning and pass the parameters for which data cleaning needs to be done and which tasks of the cleaning such as parsing or standardization etc...and after that run it and gets an output file. Is it possible with DataCleaner.
Hi Kasper,
although having limited time, would like to support you with some documentation.
Regarding the input format: you've learned already with my test feedbacks that I am an intensive MindManager user.
In the past I used it also pretty much to create operations manuals and documentations. As the information can be easily collected, grouped, regrouped and updated. If its ready, the result can be exported for example as Word file or even create a complete Website.
However, this would be a good use of my traveltime from home to work (using 30 minutes in the train to write on my laptop is ok).
What do you think about that approach ?
Best regards,
Christian
although having limited time, would like to support you with some documentation.
Regarding the input format: you've learned already with my test feedbacks that I am an intensive MindManager user.
In the past I used it also pretty much to create operations manuals and documentations. As the information can be easily collected, grouped, regrouped and updated. If its ready, the result can be exported for example as Word file or even create a complete Website.
However, this would be a good use of my traveltime from home to work (using 30 minutes in the train to write on my laptop is ok).
What do you think about that approach ?
Best regards,
Christian
Hi Christian,
Sounds like that could be a great contribution! You have shown me that you definately get a lot done and work very intensively once you take on a task! :)
The current status of the un-finished documentation for DC 2.0 you can see here:
http://eobjects.org/svn/DataCleaner/trunk/src/main/docbook/
Even though you may now know Docbook already these files should give you a sense of the current status as there is an index/TOC and some chapters with quite a lot of TODOs.
Regarding format:
Docbook is of course preferred, but not required as such. Alternatively you can provide raw text. I think a mindmap is a bit too rich - I will end up spending a lot of time converting it... Word is also OK, but try to keep the formatting etc. at a minimum. If possible only use headers, paragraphs, quote blocks and list items.
Best regards,
Kasper
Sounds like that could be a great contribution! You have shown me that you definately get a lot done and work very intensively once you take on a task! :)
The current status of the un-finished documentation for DC 2.0 you can see here:
http://eobjects.org/svn/DataCleaner/trunk/src/main/docbook/
Even though you may now know Docbook already these files should give you a sense of the current status as there is an index/TOC and some chapters with quite a lot of TODOs.
Regarding format:
Docbook is of course preferred, but not required as such. Alternatively you can provide raw text. I think a mindmap is a bit too rich - I will end up spending a lot of time converting it... Word is also OK, but try to keep the formatting etc. at a minimum. If possible only use headers, paragraphs, quote blocks and list items.
Best regards,
Kasper
Hi Kasper,
don't worry. Didn't meant to send you MindMaps only.
But with MindManager I can easily control the way the maps are exported (with/without chapters, bullets, paragraphs, etc.). So I can provide you with a simplified export in Word which should perfectly fit your "easy to convert" requirements.
So it will be text, simple headers, paragraphs and list items plus jpg-files (for the screenshots - or need any other format here ?).
If its ok for you, I will start with the "how to use" from an end-user point of view.
Soon you will ge a first documentation sample. Just to check if the format is ok for you then to convert it easily.
Best regards,
Christian
don't worry. Didn't meant to send you MindMaps only.
But with MindManager I can easily control the way the maps are exported (with/without chapters, bullets, paragraphs, etc.). So I can provide you with a simplified export in Word which should perfectly fit your "easy to convert" requirements.
So it will be text, simple headers, paragraphs and list items plus jpg-files (for the screenshots - or need any other format here ?).
If its ok for you, I will start with the "how to use" from an end-user point of view.
Soon you will ge a first documentation sample. Just to check if the format is ok for you then to convert it easily.
Best regards,
Christian
Formatting sounds fine. JPG files for screenshots are also good.
I think it's good that you will try to explain the end-user POV. Maybe you can look at the structure in the existing chapters regarding this. I'm especially thinking that maybe you can use this structure (and possibly extend with your own sections if needed):
Please add more chapters or sections if needed. I just think that this structure will be good for balancing a good "full manual read" and a quick "lookup", which is basically the two scenarios that I think people use the documentation for.
I think it's good that you will try to explain the end-user POV. Maybe you can look at the structure in the existing chapters regarding this. I'm especially thinking that maybe you can use this structure (and possibly extend with your own sections if needed):
- Chapter 2: Getting started
- Installing DataCleaner (done).
- Connecting to a datastore (TODO)
- Chapter 3: Building jobs
- Adding components to the job (TODO)
- Executing jobs (TODO)
- Saving and opening jobs (TODO)
- Template jobs (TODO)
- Chapter 4+5+6: Reference description for all components (mostly TODO)
Please add more chapters or sections if needed. I just think that this structure will be good for balancing a good "full manual read" and a quick "lookup", which is basically the two scenarios that I think people use the documentation for.
Log in by clicking the login link at the top of the screen
Go back to forum.
