64

Where should should project documentation (requirements, etc.) be stored in a typical maven project.

None of the directories listed in Introduction to the Standard Directory Layout page is an obvious candidate.

  • 3
    I would vote for '/docs'. Everything under '/src' is maven world, better not to mess with that. I also think that project itself is not good for saving documentation. Consider installing wiki. – dma_k Feb 05 '12 at 13:37
  • 1
    In maven all source files go under /src. Documents that you edit are source files, they should go under /src somewhere. If you start adding new top level directories willy nilly, then your project is not following maven conventions and will be difficult for others to comprehend. – dan carter Apr 07 '14 at 01:07

3 Answers3

59

Unfortunately there is no convention. If you want the documentation to be part of the generated site, obviously /src/site is a good place. Maybe you can even write the documentation in the APT format?

But more likely you have a set of doc, pdf and xls files, graphics, e-mails, etc. You can either place them under /src/site as well and put hyperlinks in the site or... define your own convention, sadly. Typically I have seen /src/main/doc(s), /src/doc(s) or even /doc(s).

You don't want to place your documentation in /src/main/resources or src/main/webapp, as the files will then be part of built artifact (JAR/WAR) which is rarely desired.

Tomasz Nurkiewicz
  • 334,321
  • 69
  • 703
  • 674
  • Is't src rather for source? – Line Jun 01 '17 at 13:47
  • 1
    If your doc format is processed into other formats, it is the source for documentation, so placing it under src would make sense (/src/main/doc for documentation of the code, /src/doc for documentation of the project). If the documentation files are to be used "as is", then a /doc in parallel to /src seems more logical. – foo Feb 21 '19 at 09:51
3

http://www.sonatype.com/books/mvnref-book/reference/site-generation-sect-dir-struct.html recommends the following structure

sample-project
+- src/
[..]
+- resources/
|  +- images/
|  |  +- banner-left.png
|  |  +- banner-right.png
|  |
|  +- architecture.html
|  +- jira-roadmap-export-2007-03-26.html
[..]
rob2universe
  • 7,059
  • 39
  • 54
  • 2
    I don't know why Joao edited this post instead of posting an alternate suggestion. He places the resources folder under the site folder which certainly is also a valid option. The suggestion I posted/quoted uses a resources folder on the top level next to the src and site folders (see link in the post). One does not necessarily want to include all documentation in the site. – rob2universe Aug 22 '13 at 09:40
  • Sorry @RobE, my mistake. – Joao Piccinini Jan 27 '14 at 11:32
3

According to the maven-javadoc-plugin:

The <javadocDirectory/> parameter can be used to include additional resources, like HTML or images, in the generated javadoc. You can then link to these resources in your javadoc comments. By default, all javadoc resources are in ${basedir}/src/main/javadoc directory. Note that you need to set the docfilessubdirs parameter to copy these.

Alun
  • 541
  • 6
  • 16
  • 3
    Do you see the difference between documentation in general and JavaDoc? :) – Line Jun 01 '17 at 13:47
  • Somewhat. If you view JavaDoc as a format/documentation generator, the problem is never documenting just the APIs, but writing the docs around them which explain their use. Having that *in* the JavaDocs/Code, and linking to the APIs, always seems to be a good idea. If you are documenting something *other* than the APIs, I would think something else could be used (e.g. markdown). – Alun Jun 05 '17 at 03:13