[jira] [Comment Edited] (PDFBOX-2340) Overhaul PDFBox Documentation

["Tilman Hausherr (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/PDFBOX-2340?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14137665#comment-14137665 ] 

Tilman Hausherr edited comment on PDFBOX-2340 at 9/17/14 6:08 PM:
------------------------------------------------------------------

While the mockups looks very nice, I'm more a content guy who doesn't care about looks (this only applies to software :-) ). There are two things that are missing in the documentation, one is sample code for rendering, the other is an improved text for people opening issues. Here's a text that could be merged with the existing text at https://pdfbox.apache.org/support.html

We want to help you. We don't respond by clicking on boilerplate texts. Solving your issues is what makes PDFBox better and better!

Do's:
- attach the PDF that makes trouble by using "More", "Attach files". 
- If your file is too large, upload it to a sharehoster, or use the PDFSplit application to isolate the troublesome page
- Mention the PDFBox version you are using.
- Attach the shortest possible code that reproduces the problem. Insert java code between \{code\}...\{code\}. Or try to reproduce the problem with the command line applications.
- mention what you were doing, what was the expected behaviour, and what happened instead
- Provide a stack trace of an exception if there is one
- Try using the non-sequential parser (loadNonSeq() instead of load(), and "-nonSeq" with the command line applications)
- Search JIRA if your problem has been mentioned before.
- Be patient: all the people here are unpaid volunteers who work for you in their free time

Dont's:
- upload files to a hoster that requires registration to read the file.
- create an issue in JIRA and then go on vacation so you won't repond to our questions / suggestions.
- ask "how to" questions. Ask such questions on the mailing lists, on stackoverflow.com, and look at the sample and the test code in the sources.
- attach PDF files with confidential and/or personal data (name, DoB, bank data, health data, SSN) without getting permission from the client and/or the people mentioned on the PDF
- create issues about obsolete PDFBox versions

We can sometimes solve problems without having the PDF, but it is difficult.



was (Author: tilman):
While it looks very nice, I'm more a content guy who doesn't care about looks (this only applies to software :-) ). There are two things that are missing in the documentation, one is sample code for rendering, the other is an improved text for people opening issues. Here's a text that could be merged with the existing text at https://pdfbox.apache.org/support.html

We want to help you. We don't respond by clicking on boilerplate texts. Solving your issues is what makes PDFBox better and better!

Do's:
- attach the PDF that makes trouble by using "More", "Attach files". 
- If your file is too large, upload it to a sharehoster, or use the PDFSplit application to isolate the troublesome page
- Mention the PDFBox version you are using.
- Attach the shortest possible code that reproduces the problem. Insert java code between \{code\}...\{code\}. Or try to reproduce the problem with the command line applications.
- mention what you were doing, what was the expected behaviour, and what happened instead
- Provide a stack trace of an exception if there is one
- Try using the non-sequential parser (loadNonSeq() instead of load(), and "-nonSeq" with the command line applications)
- Search JIRA if your problem has been mentioned before.
- Be patient: all the people here are unpaid volunteers who work for you in their free time

Dont's:
- upload files to a hoster that requires registration to read the file.
- create an issue in JIRA and then go on vacation so you won't repond to our questions / suggestions.
- ask "how to" questions. Ask such questions on the mailing lists, on stackoverflow.com, and look at the sample and the test code in the sources.
- attach PDF files with confidential and/or personal data (name, DoB, bank data, health data, SSN) without getting permission from the client and/or the people mentioned on the PDF
- create issues about obsolete PDFBox versions

We can sometimes solve problems without having the PDF, but it is difficult.


> Overhaul PDFBox Documentation
> -----------------------------
>
>                 Key: PDFBOX-2340
>                 URL: https://issues.apache.org/jira/browse/PDFBOX-2340
>             Project: PDFBox
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Maruan Sahyoun
>         Attachments: Mockup-20140912.png, Mockup_Documentation.png
>
>
> In oder to make it easier for users of PDFBox to work with the library there shall be an enhanced documentation consisting of an introduction, API references and more well documented examples and code snippets (Cookbook).
> In order to make it easier to contribute the Cookbook shall be build automatically from the examples/snippet ‚repository‘.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)