Just had a first glance at section one of the manual. It looks very nice but it is unstructured word processed text - ie. everything is styled “default”. So there are no shortcuts to be had - conversion to docbook and creation of structure for the document will be manual. I guess the others will be the same. This will be a bit painful but will add considerable value to the documentation.
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
The intrinsic problem with formats such as DockuWiki is that they are pretty much a one way street. It is an easy format to use, but not entirely easy to transform into something else. Pure XML formats such as DocBook separate entirely the content away from the presentation. Want Word? No problem. How about PDF? Can do. How about an integrated help system with the application? Should not be an issue as you have pure XML to work with.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
Basically, I tried a number of ways to get the manual in this format, but the easiest I think was simply copying and pasting chunks of text into XXE (a docbook editor). I just could not get any of the exporters to work very well (YAWC, XMLSpy were the ones I tried). This initial conversion took about 30 minutes for this doucment, so it was not too painful.
As you say, there are essentially no style information at the moment. I guess this would need to be handled by the XSL with appropriate tags in the source document.
This should be able to be added as we go along.
Just had a first glance at section one of the manual. It looks very nice but it is unstructured word processed text - ie. everything is styled “default”. So there are no shortcuts to be had - conversion to docbook and creation of structure for the document will be manual. I guess the others will be the same. This will be a bit painful but will add considerable value to the documentation.
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
The intrinsic problem with formats such as DockuWiki is that they are pretty much a one way street. It is an easy format to use, but not entirely easy to transform into something else. Pure XML formats such as DocBook separate entirely the content away from the presentation. Want Word? No problem. How about PDF? Can do. How about an integrated help system with the application? Should not be an issue as you have pure XML to work with.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
Oh, forgot to add, maybe someone that understand maven better than I do (pretty much everyone) can use/modify this to automate the building of the documentation.
Basically, I tried a number of ways to get the manual in this format, but the easiest I think was simply copying and pasting chunks of text into XXE (a docbook editor). I just could not get any of the exporters to work very well (YAWC, XMLSpy were the ones I tried). This initial conversion took about 30 minutes for this doucment, so it was not too painful.
As you say, there are essentially no style information at the moment. I guess this would need to be handled by the XSL with appropriate tags in the source document.
This should be able to be added as we go along.
Just had a first glance at section one of the manual. It looks very nice but it is unstructured word processed text - ie. everything is styled “default”. So there are no shortcuts to be had - conversion to docbook and creation of structure for the document will be manual. I guess the others will be the same. This will be a bit painful but will add considerable value to the documentation.
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
The intrinsic problem with formats such as DockuWiki is that they are pretty much a one way street. It is an easy format to use, but not entirely easy to transform into something else. Pure XML formats such as DocBook separate entirely the content away from the presentation. Want Word? No problem. How about PDF? Can do. How about an integrated help system with the application? Should not be an issue as you have pure XML to work with.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
Well, it was actually not so difficult. I have just commited in 687 which will allow for automated documentation builds for documentation in DocBook format stored in the /dhis2/docs/src/docbook directory
Just execute
mvn docbook:transform
in the docs directory. You will find the HTML files in /docs/target/site/docbook/.
I think someone that understands maven needs to modify that pom.xml file a bit. All images that the DocBook source file needs to reference need to be stored somewhere., and then I guess copied over to the target directory during the build.
I guess we should add other formats as well, such as PDF. It should be possible, but I do not know enough about maven to make it work. I just copied that pom.xml file from the site in my previous mail and it worked pretty much magically.
I modified the directory structure a bit as well to fit the needs of maven. Perhaps they need to be standardized a bit to fit the rest of the project.
Oh, forgot to add, maybe someone that understand maven better than I do (pretty much everyone) can use/modify this to automate the building of the documentation.
Basically, I tried a number of ways to get the manual in this format, but the easiest I think was simply copying and pasting chunks of text into XXE (a docbook editor). I just could not get any of the exporters to work very well (YAWC, XMLSpy were the ones I tried). This initial conversion took about 30 minutes for this doucment, so it was not too painful.
As you say, there are essentially no style information at the moment. I guess this would need to be handled by the XSL with appropriate tags in the source document.
This should be able to be added as we go along.
Just had a first glance at section one of the manual. It looks very nice but it is unstructured word processed text - ie. everything is styled “default”. So there are no shortcuts to be had - conversion to docbook and creation of structure for the document will be manual. I guess the others will be the same. This will be a bit painful but will add considerable value to the documentation.
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
The intrinsic problem with formats such as DockuWiki is that they are pretty much a one way street. It is an easy format to use, but not entirely easy to transform into something else. Pure XML formats such as DocBook separate entirely the content away from the presentation. Want Word? No problem. How about PDF? Can do. How about an integrated help system with the application? Should not be an issue as you have pure XML to work with.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway…
Just execute…
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Well, it was actually not so difficult. I have just commited in 687 which will allow for automated documentation builds for documentation in DocBook format stored in the /dhis2/docs/src/docbook directory
Just execute
mvn docbook:transform
in the docs directory. You will find the HTML files in /docs/target/site/docbook/.
I think someone that understands maven needs to modify that pom.xml file a bit. All images that the DocBook source file needs to reference need to be stored somewhere., and then I guess copied over to the target directory during the build.
I guess we should add other formats as well, such as PDF. It should be possible, but I do not know enough about maven to make it work. I just copied that pom.xml file from the site in my previous mail and it worked pretty much magically.
I modified the directory structure a bit as well to fit the needs of maven. Perhaps they need to be standardized a bit to fit the rest of the project.
Oh, forgot to add, maybe someone that understand maven better than I do (pretty much everyone) can use/modify this to automate the building of the documentation.
Basically, I tried a number of ways to get the manual in this format, but the easiest I think was simply copying and pasting chunks of text into XXE (a docbook editor). I just could not get any of the exporters to work very well (YAWC, XMLSpy were the ones I tried). This initial conversion took about 30 minutes for this doucment, so it was not too painful.
As you say, there are essentially no style information at the moment. I guess this would need to be handled by the XSL with appropriate tags in the source document.
This should be able to be added as we go along.
Just had a first glance at section one of the manual. It looks very nice but it is unstructured word processed text - ie. everything is styled “default”. So there are no shortcuts to be had - conversion to docbook and creation of structure for the document will be manual. I guess the others will be the same. This will be a bit painful but will add considerable value to the documentation.
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
The intrinsic problem with formats such as DockuWiki is that they are pretty much a one way street. It is an easy format to use, but not entirely easy to transform into something else. Pure XML formats such as DocBook separate entirely the content away from the presentation. Want Word? No problem. How about PDF? Can do. How about an integrated help system with the application? Should not be an issue as you have pure XML to work with.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
I have reorganized the directory structure a little. I put the maven project in a separate directory called “dhis-documentation-docbook” and used the same name for the project’s artifact id. Also removed the packaging: pom element, which now makes it possible to execute “mvn eclipse:eclipse” and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don’t want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work… I hope other people using the system will follow his example and contribute to this process.
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway…
Just execute…
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars.
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway…
Just execute…
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called “dhis-documentation-docbook” and used the same name for the project’s artifact id. Also removed the packaging: pom element, which now makes it possible to execute “mvn eclipse:eclipse” and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don’t want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work… I hope other people using the system will follow his example and contribute to this process.
I am not that familiar with Launchpad, but it would seem that perhaps
a separate group/team should be added as the owner should be added
instead of the DHIS2 devs so that access could be controlled?
Regards,
Jason
···
2009/9/17 Jason Pickering <jason.p.pickering@gmail.com>
Hi Lars,
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars.
Best regards,
jason
2009/9/17 Lars Helge Øverland <larshelge@gmail.com>
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering <jason.p.pickering@gmail.com> wrote:
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway..
Just execute..
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called "dhis-documentation-docbook" and used the same name for the project's artifact id. Also removed the packaging: pom element, which now makes it possible to execute "mvn eclipse:eclipse" and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don't want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work... I hope other people using the system will follow his example and contribute to this process.
I am not that familiar with Launchpad, but it would seem that perhaps
a separate group/team should be added as the owner should be added
instead of the DHIS2 devs so that access could be controlled?
Regards,
Jason
2009/9/17 Jason Pickering <jason.p.pickering@gmail.com>
Hi Lars,
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars.
Best regards,
jason
2009/9/17 Lars Helge Øverland <larshelge@gmail.com>
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering <jason.p.pickering@gmail.com> wrote:
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway..
Just execute..
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called "dhis-documentation-docbook" and used the same name for the project's artifact id. Also removed the packaging: pom element, which now makes it possible to execute "mvn eclipse:eclipse" and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don't want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work... I hope other people using the system will follow his example and contribute to this process.
Please add me to the team. I haven’t had much chance to follow the past week but will get involved soon.
I have been recently growing fond of editx (http://www.editix.com/) as a generic xml editor. I am mostly using it for xslt but it seems to have quite a good docbook mode, perhaps for the more technical of authors.
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars.
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway…
Just execute…
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called “dhis-documentation-docbook” and used the same name for the project’s artifact id. Also removed the packaging: pom element, which now makes it possible to execute “mvn eclipse:eclipse” and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don’t want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work… I hope other people using the system will follow his example and contribute to this process.
Hi there. Yes, I think this is reasonable. I will add the dhis2-devs
to the team, and then as more documenters (hopefully) come on board we
can add them to the team without adding them to the dhis2-devs team.
Lars, does this solve the issue of allowing documenters to commit to
the documentation branch, without having write access to the source
code?
Regards,
Jason
···
On Fri, Sep 18, 2009 at 12:23 PM, Jo Størset <storset@gmail.com> wrote:
Den 18. sep. 2009 kl. 10.23 skrev Bob Jolliffe:
Hi Jason
Please add me to the team. I haven't had much chance to follow the past
week but will get involved soon.
Nice work. Did you make the team a restricted one? (Implies that we can approve who will have write access). I agree we should add the team, but rather the dhis2-devs-core team, which is restricted (the dhis2-devs team is open). By doing this we will solve the issue you mention.
Hi there.
OK, I added Bob and Jo separately as requested, as well as the
dhis2-devs-core team. Launchpad says that it sent an invitation to
join the team. I guess the team's owner needs to approve it.
I created it as a moderated group, which means that people can request
approval.
Hope this solves these issue and we can get down to writing some docs!
Regards,
Jason
···
On Fri, Sep 18, 2009 at 12:37 PM, Lars Helge Øverland <larshelge@gmail.com> wrote:
On Fri, Sep 18, 2009 at 12:33 PM, Jason Pickering > <jason.p.pickering@gmail.com> wrote:
Hi there. Yes, I think this is reasonable. I will add the dhis2-devs
to the team, and then as more documenters (hopefully) come on board we
can add them to the team without adding them to the dhis2-devs team.
Lars, does this solve the issue of allowing documenters to commit to
the documentation branch, without having write access to the source
code?
Regards,
Jason
Nice work. Did you make the team a restricted one? (Implies that we can
approve who will have write access). I agree we should add the team, but
rather the dhis2-devs-core team, which is restricted (the dhis2-devs team is
open). By doing this we will solve the issue you mention.
What is the plan for converting the current dhis2 technical architecture documentation to docbook? Thinking of updating it with the latest development regarding struts, spring transaction management etc.
On Fri, Sep 18, 2009 at 1:01 PM, Lars Helge Øverland <larshelge@gmail.com> wrote:
On Fri, Sep 18, 2009 at 12:45 PM, Jason Pickering > <jason.p.pickering@gmail.com> wrote:
Hi there.
OK, I added Bob and Jo separately as requested, as well as the
dhis2-devs-core team. Launchpad says that it sent an invitation to
join the team. I guess the team's owner needs to approve it.
I created it as a moderated group, which means that people can request
approval.
Hope this solves these issue and we can get down to writing some docs!
Regards,
Jason
Perfect. Johan has approved the team membership.
What is the plan for converting the current dhis2 technical architecture
documentation to docbook? Thinking of updating it with the latest
development regarding struts, spring transaction management etc.
I am not sure about this. I just noticed that the DHIS2 documentation
team was not listed as a subteam to any groups. The documentation team
should probably somehow be converted to a subteam of the dhis2-devs
team. I am not sure what this implies for commits and access, but
there would seem to need to be an invitation sent from an
owner/administrator of the main team.
Lars?
Regards,
Jason
···
On Fri, Sep 18, 2009 at 6:23 PM, Jason Pickering <jason.p.pickering@gmail.com> wrote:
Great.
Just convert it a commit it.
Regards,
Jason
On Fri, Sep 18, 2009 at 1:01 PM, Lars Helge Øverland > <larshelge@gmail.com> wrote:
On Fri, Sep 18, 2009 at 12:45 PM, Jason Pickering >> <jason.p.pickering@gmail.com> wrote:
Hi there.
OK, I added Bob and Jo separately as requested, as well as the
dhis2-devs-core team. Launchpad says that it sent an invitation to
join the team. I guess the team's owner needs to approve it.
I created it as a moderated group, which means that people can request
approval.
Hope this solves these issue and we can get down to writing some docs!
Regards,
Jason
Perfect. Johan has approved the team membership.
What is the plan for converting the current dhis2 technical architecture
documentation to docbook? Thinking of updating it with the latest
development regarding struts, spring transaction management etc.
Not sure either, but I don’t think there is a need to add people who are a member of dhis-devs-core explicitly, as they will be members of dhis-documenters “transitively” through the dhis-devs-core team. Not sure about subteams but is seems sufficient to me to have dhis-devs-core being as a members of dhis-documenters. We could try to remove the individual members and see if it still works.
Jason and others,
Thanks for this initiative. A structured approach to documentation will be the right, professional way.
However, in the area of user documentation and tutorials, there will be people like me, who are not software developers, and who do not understand what we should do with the code
bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
There are also people who could contribute, who come from the health background without being computer scientists, and who would also feel alienated by the ideas of XML, structured documents, etc. I could take on the challenge of trying to accommodate these, but then I would need
- to be included in the documentation group
- to get a crash course on bzrs and other TLAs.
Best regards,
Jens Kaasb�ll
Univ Oslo
···
On 17.09.2009 22:59, Jason Pickering wrote:
OK, i think i solved that problem as well. I created a new team
(dhis2-documenters). The new branch is available here.
I am not that familiar with Launchpad, but it would seem that perhaps
a separate group/team should be added as the owner should be added
instead of the DHIS2 devs so that access could be controlled?
Regards,
Jason
2009/9/17 Jason Pickering <jason.p.pickering@gmail.com>
Hi Lars,
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars.
Best regards,
jason
2009/9/17 Lars Helge �verland <larshelge@gmail.com>
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering <jason.p.pickering@gmail.com> wrote:
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway..
Just execute..
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called "dhis-documentation-docbook" and used the same name for the project's artifact id. Also removed the packaging: pom element, which now makes it possible to execute "mvn eclipse:eclipse" and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don't want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work... I hope other people using the system will follow his example and contribute to this process.
Hi Jens,
Thanks for the feedback. You raise some good points. The community
seems to agree that the move to a structured format is the way to go,
but we need to ensure that it does not become an exclusive process. I
would not regard myself as a software developer either, but am
comfortable using some of their tools. The question is whether others
that may want to contribute to the documentation process will be
comfortable using these tools as well. I think we have still not
answered this question, and why I would still regard the move to
DocBook as the primary means of documentation for DHIS as
experimental.
I have started with a DHIS 2 documentation development guide, but have
not included a step-by-step of how to get started. If I expanded this
doucment a bit, would you be willing to be a guinea pig and see if it
is a feasible process for you and others that may want to contriubute?
Best regards,
Jason
···
On Thu, Sep 24, 2009 at 9:54 PM, Jens Kaasbøll <jensj@ifi.uio.no> wrote:
Jason and others,
Thanks for this initiative. A structured approach to documentation will be
the right, professional way.
However, in the area of user documentation and tutorials, there will be
people like me, who are not software developers, and who do not understand
what we should do with the code
bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
There are also people who could contribute, who come from the health
background without being computer scientists, and who would also feel
alienated by the ideas of XML, structured documents, etc. I could take on
the challenge of trying to accommodate these, but then I would need
- to be included in the documentation group
- to get a crash course on bzrs and other TLAs.
Best regards,
Jens Kaasbøll
Univ Oslo
On 17.09.2009 22:59, Jason Pickering wrote:
OK, i think i solved that problem as well. I created a new team
(dhis2-documenters). The new branch is available here.
I am not that familiar with Launchpad, but it would seem that perhaps
a separate group/team should be added as the owner should be added
instead of the DHIS2 devs so that access could be controlled?
Regards,
Jason
2009/9/17 Jason Pickering <jason.p.pickering@gmail.com>
Hi Lars,
Glad to see you had a chance to review it. I hope it will catch on. I
know it is a bit more effort, but with all those semi-WYSIWYG editors out
there, it is not much more difficult that creating a Word document. There
are going to be some compromises of course in terms of layout initially. The
HTML is rendered a bit better now with the addition of a style sheet, but it
will probably take a lot more tweaking. However, the important thing to
remember is that any documentation, even if it is a bit ugly, is better than
none at all! We still need to figure out what to do with the DokuWiki and
other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in
the long run. Most people that want to contribute to documentation do not
generally need all of the source code as well, and if the devs want to
contribute to the documentation, well, it is simple enough to do this.
Before we do this however, I think we should somehow formally endorse that
DocBook (or similar presentation neutral XML documents) is the way we want
to go.
I am still willing to coordinate the effort for the time being. This may
be a better short-term solution, so that we can continue to guage what the
interest is in heading this direction with the documentation. Thinking
long-term, I suppose it is no problem that the documentation is in a
separated branch? Ideally, with some sort of integrated help system that is
able to access the documentation directly, we would need to include the
documentation build as part of the entire DHIS2 build process. I guess this
is not an issue, but as I have said previously, maven is just juju for me.
But thank goodness, we have Lars.
Best regards,
jason
2009/9/17 Lars Helge Øverland <larshelge@gmail.com>
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering >>>>> <jason.p.pickering@gmail.com> wrote:
I have just committed in 731 some changes to the documentation system.
After a bit of experimentation, it would seem that at least for now, the
maven plugin docbkx is a better choice than the previous dependency. I was
having issues with the other dependency, so thought I would try some others.
Anyway..
Just execute..
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that
are present.
There seem to be a lot more possibilities with this dependency, but it
is a rather heavy download the first time you try and compile the
documentation (at least in Zambia).
One of the reasons that I decided to move to this for now was that it
seems to be under active development, actually has a mailing list, and good
enough documentation for me to understand, (which must mean it is pretty
good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look
crappy, but I guess we could make one similar to the DHIS CSS in order to
standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven
project in a separate directory called "dhis-documentation-docbook" and used
the same name for the project's artifact id. Also removed the packaging: pom
element, which now makes it possible to execute "mvn eclipse:eclipse" and
then import the project directly into eclipse. All this to make it conform
to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was
Serna Free 4.2, which formats the xml nicely and makes it easy to
insert/modify elements in the document. It is free and under active
development. Vex worked reasonably well, but is not so easy-to-use as Serna.
Also the Eclipse plugin version did not work in my Eclipse installation
(Galileo 3.5) and I had to download the stand-alone version (my guess is
that this happens because it is no longer under active development.)
One question is how to provide access to documentation writers. By
giving people write access to the documentation we also give them write
access to the whole branch, including the source code, which is something we
don't want to do. A weakness with Launchpad is that we cannot give people
access to only parts of a branch. My suggestion is to create a new,
dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important
work... I hope other people using the system will follow his example and
contribute to this process.
