search

opensagres / xdocreport

XDocReport means XML Document reporting. It's Java API to merge XML document created with MS Office (docx) or OpenOffice (odt), LibreOffice (odt) with a Java model to generate report and convert it if you need to another format (PDF, XHTML...).
https://github.com/opensagres/xdocreport
1.22k stars 373 forks source link

process to contribute to documentation #55

Open mohamnag opened 9 years ago

mohamnag commented 9 years ago

As I'm trying to learn XDocReport, I stumbled on to the fact that docs need much attention. Maybe what a developer new to project can much better do is to contribute to documents.

However collaboration on GitHub wikis are not as easy as normal repositories, therefore if contributors setup a mirror repo for wikis as described here any body may contribute to docs much easier.

angelozerr commented 9 years ago

Yes there are a problem with XDocReport documentation. We have exported teh doc from https://code.google.com/p/xdocreport/wiki/Overview?tm=6 to GitHub but the result is not very good.

I have spend a lot of time to fix problem (like file name which is not correct) but it takes a long time (I'm a little discouraged).

I have unactivated the collaboration of the wiki because some user clicked on some link (which was not correct because file name was not correct) and saved the page with bad content.

I can re-activate the collaboration if you wish to contribute but pay attention with broken link.

mohamnag commented 9 years ago

I would gladly do some changes as I go on with reading the manuals, however this collaboration feature of GitHub's wikis are not really useful as anybody may then edit your pages.

If you use a mirror repo as described on the link from first post, you have the total control and other developers have to submit merge requests which can only be approved by you. So this is a much cleaner workflow.

However any way that you decide to use, I can try to fix parts of docs that I read.

angelozerr commented 9 years ago

@pascalleclercq what do you think, perhaps we should do http://nerds.inn.org/2014/05/19/applying-git-to-github-wikis/ like @mohamnag suggested?

angelozerr commented 9 years ago

@mohamnag for the moment I have re-activated the collaboration. You can update page if you wish. Thanks!

mohamnag commented 9 years ago

that will do for now!

mohamnag commented 9 years ago

guys as much as I work with this lib, the more I'm in love with it, this a great piece of work that deserves much more attention!

angelozerr commented 9 years ago

guys as much as I work with this lib, the more I'm in love with it, this a great piece of work that deserves much more attention!

Glad XDocReport please you!

Today we are very busy, so any contribution are welcome!

mohamnag commented 9 years ago

I would love to, maybe not code for now but will try to help with docs

mohamnag commented 9 years ago

PS: maybe I can even help with a very basic standard web page if that makes sense

angelozerr commented 9 years ago

PS: maybe I can even help with a very basic standard web page if that makes sense

Sorry I don't understand? You mean a demo with XDocReport?

mohamnag commented 9 years ago

I meant a website for XDocReport, if there isn't any yet. I did not find any at least.

angelozerr commented 9 years ago

I meant a website for XDocReport

I'm really sorry, but what do you mean with website. Our wiki is not enough?

mohamnag commented 9 years ago

sure wiki is enough (after being updated) I only thought maybe for some library of this level it is nice to have own domain. Even if this is the wiki content that is shown on that own domain. But that was only an idea.

also back to updating wiki, I think there are a lot of redundant things that best be gathered on one place for easier maintenance. Like listing all the dependencies on one page instead of in each single guide (for Docx, ODP, ...) this way only one page shall be update if something changes. what do you think?

angelozerr commented 9 years ago

We have written doc as soon as features was developped, so I agree with you, documentation can be bad sometimes.

Like listing all the dependencies on one page instead of in each single guide (for Docx, ODP, ...)

IMHO, I think it's better to have a doc per document kind. user can copy/paste directly the code and we can add a screenshot per document kind. More some features are implemented for some docume,nt kind (like html text styling) an dnot for other document kind.

mohamnag commented 9 years ago

I only meant the list of dependencies. The guide for each type should definietly be done separately.

On Wed, Aug 5, 2015, 5:17 PM Angelo notifications@github.com wrote:

We have written doc as soon as features was developped, so I agree with you, documentation can be bad sometimes.

Like listing all the dependencies on one page instead of in each single guide (for Docx, ODP, ...)

IMHO, I think it's better to have a doc per document kind. user can copy/paste directly the code and we can add a screenshot per document kind. More some features are implemented for some docume,nt kind (like html text styling) an dnot for other document kind.

— Reply to this email directly or view it on GitHub https://github.com/opensagres/xdocreport/issues/55#issuecomment-128033702 .