[
https://issues.apache.org/jira/browse/DERBY-6466?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13943772#comment-13943772
]
Bryan Pendleton commented on DERBY-6466:
----------------------------------------
Your revised proposal looks good. I am able to see the proposal on the Google
GSoC website,
so it appears that you have entered it in the system successfully.
I think that paying particular attention to the performance tuning sections of
the
documentation will be very valuable. We frequently get questions on the mailing
lists and on discussion sites such as StackExchange regarding the performance
of Derby, so ensuring that our performance-related documentation is as good as
possible will be very much appreciated by the community.
Here are a few more suggestions for your proposal:
1) The most important document that we will be working to improve is the
Derby Tuning Guide, so you should add a direct link to that manual in your
proposal: http://db.apache.org/derby/docs/10.10/tuning/
2) As you noted, there are also sections regarding performance in the
Derby Developer's Guide, such as the discussion of in-memory
database, the section on locking and concurrency, and the "SQL Tips"
section, so you should add a direct link to that manual in your proposal
too: http://db.apache.org/derby/docs/10.10/devguide/
It would be good if you could expand on some ideas about *how* we
can verify and improve the documentation on performance tuning.
For example, we could:
1) Write and run simple benchmarks to confirm the suggestions
made in the documentation.
2) Conduct "before and after" experiments in which we build an
application which has a performance problem, then make some of
the improvements suggested in the documentation, and show how
the various performance tools (query plans, runtime statistics, etc.)
change as a result of those modifications.
3) We can look through issues in the Derby JIRA database in the
"performance" category, both open issues and closed issues, and
see if the documentation accurately describes the approaches to
the performance problems.
Perhaps you can include some additional ideas as you think about
the problem some more.
Congratulations on submitting your proposal, and thanks for being
interested in Derby!
bryan
> GSOC 2014: Thorough documentation review
> ----------------------------------------
>
> Key: DERBY-6466
> URL: https://issues.apache.org/jira/browse/DERBY-6466
> Project: Derby
> Issue Type: Improvement
> Components: Demos/Scripts, Documentation
> Reporter: Bryan Pendleton
> Labels: database, documentation, gsoc2014, java, jdbc
>
> For the 2014 Google Summer of Code, I am volunteering to mentor a student to
> conduct a thorough top-to-bottom, start-to-finish review of all of the Derby
> documentation.
> A product as powerful and sophisticated as Derby depends crucially on its
> documentation, and part of the software process for any engineer is to learn
> how to write clearly, to learn how to use the tools and coding languages that
> are used by technical writers, and to learn how to contribute to the
> documentation process.
> This project will help you develop and improve those skills, as you embark
> upon the career of a software professional.
> The Derby documentation is composed of several major pieces:
> 1) The primary manual set is published on the Derby website:
> http://db.apache.org/derby/docs/10.10/
> 2) Additional papers and documentation are on the website:
> http://db.apache.org/derby/papers/index.html
> 3) There is a large Derby wiki: http://wiki.apache.org/db-derby/
> 4) The Derby distribution contains some samples and demo scripts.
> Overall, the documentation is extensive and sophisticated; the Derby
> community has enjoyed the participation of several skilled technical writers
> over the years who have contributed superb documentation to the project.
> But documentation, like everything else, needs maintenance and attention.
> In this Google Summer of Code project, during the summer of 2014, the project
> will include (at least) the following:
> 1) We'll read through each of the manuals, wiki pages, and papers.
> 2) We'll look for typos, grammatical problems, or out-of-date and inaccurate
> material
> 3) (THIS IS IMPORTANT) For each place where there is an example or sample
> code, we'll test that sample code, by exercising it both on Windows and on
> Linux, using the latest Java runtimes and the latest Derby distribution, to
> verify that the samples are correct and accurate.
> 4) Each time we find a problem, we'll log it as an issue in the Derby issue
> tracker, prepare a patch to the documentation, and get that patch committed.
> If the problem is in the wiki, we'll edit and repair the wiki.
> 5) As we find opportunities for larger-scoped improvements to the
> documentation, we'll also file those as issues in the Derby issue tracker, so
> that they can be worked on as time permits.
> 6) We'll also review all the existing open documentation and demo/script
> issues in the tracker (there aren't very many), to verify that they are clear
> and complete, and to see if we can contribute fixes for any of them.
--
This message was sent by Atlassian JIRA
(v6.2#6252)
