Maven
  1. Maven
  2. MNG-2143

Proposition of documentation

    Details

    • Complexity:
      Intermediate
    • Number of attachments :
      3

      Description

      Here attached are 2 apt file that describe a first attempt to refactor the maven documentation site.

      1. AdvancedDocumentation.apt
        2 kB
        Raphaël Piéroni
      2. Categories.txt
        5 kB
        Raphaël Piéroni
      3. MainPage.apt
        1 kB
        Raphaël Piéroni

        Issue Links

          Activity

          Hide
          Raphaël Piéroni added a comment -

          I think the first part of the refactor task should be to find the categories.
          Here are the categories i saw:

          Archetypes
          Testing
          This category includes unit testing and integration testing
          Maven tools
          For talking about the other programs like the ant tasts and the repository manager
          Maven extension development
          For creating plugins and archetypes
          Generating sources
          Site
          This is for the project developer site with sub categories
          Quality for reports like PMD, checkstyle, surefire, ...
          Documentation for reports like javadoc, jxr, ...
          Information for reports like mailing list, issue trasker, ...
          Ide
          For using maven in an ide
          Deployments
          For deploying artifacts into repositories, application servers
          Associated artifacts
          For creating and attaching some associated artifacts like sources, javadoc, ...
          Packagings
          For talking about alternative packagings like war, ear, ...
          Alternative languages
          For using maven with other languages like c#, aspecjt, ...
          Continuous integration
          For using maven with a continuous integration system

          Then we should put guides and plugins into the categories.
          Some plugins may belong into more than one category.

          We also need some basic documentation for talking about
          theorical concepts like packagings, repositories, ...

          Then write the site...

          Show
          Raphaël Piéroni added a comment - I think the first part of the refactor task should be to find the categories. Here are the categories i saw: Archetypes Testing This category includes unit testing and integration testing Maven tools For talking about the other programs like the ant tasts and the repository manager Maven extension development For creating plugins and archetypes Generating sources Site This is for the project developer site with sub categories Quality for reports like PMD, checkstyle, surefire, ... Documentation for reports like javadoc, jxr, ... Information for reports like mailing list, issue trasker, ... Ide For using maven in an ide Deployments For deploying artifacts into repositories, application servers Associated artifacts For creating and attaching some associated artifacts like sources, javadoc, ... Packagings For talking about alternative packagings like war, ear, ... Alternative languages For using maven with other languages like c#, aspecjt, ... Continuous integration For using maven with a continuous integration system Then we should put guides and plugins into the categories. Some plugins may belong into more than one category. We also need some basic documentation for talking about theorical concepts like packagings, repositories, ... Then write the site...
          Hide
          Raphaël Piéroni added a comment -

          I copy an extract of the initial proposition from my post in the dev list:

          So here is a cleaner proposition for the site.
          This proposition is focused on the documentation for the user.

          I assume the user is a java developer but may not be a maven developer.
          What do a developer (and maven user) want to know:

          • where to find the software,
          • how to install it,
          • how to configure maven use in a proper environment,
          • how to configure it's project,
          • how to run maven and get it project properly packaged.

          Therefore i propose the following presentation of the maven site.
          Reading Convention: a is a link to "a", (text) is a comment, <text> is
          a variable
          Main page :
          <Title missing>
          what is maven ?
          download
          installation
          getting started

          Maven Concepts
          introduction
          project descriptor
          artifact
          life cycle
          repositories
          plugins
          directory convention
          archetypes

          Normative References
          Project Object Model
          User Settings

          [SNIP]

          End of page

          Show
          Raphaël Piéroni added a comment - I copy an extract of the initial proposition from my post in the dev list: So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: where to find the software, how to install it, how to configure maven use in a proper environment, how to configure it's project, how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: a is a link to "a", (text) is a comment, <text> is a variable Main page : <Title missing> what is maven ? download installation getting started Maven Concepts introduction project descriptor artifact life cycle repositories plugins directory convention archetypes Normative References Project Object Model User Settings [SNIP] End of page
          Hide
          Raphaël Piéroni added a comment -

          I also attach a first attempt of categorisation. but it is not complete as some plugins/guides are not yet put in category. It may show that ther are more categories than i think.

          Show
          Raphaël Piéroni added a comment - I also attach a first attempt of categorisation. but it is not complete as some plugins/guides are not yet put in category. It may show that ther are more categories than i think.
          Hide
          Vincent Siveton added a comment -

          seems to be out of date

          Show
          Vincent Siveton added a comment - seems to be out of date

            People

            • Assignee:
              Vincent Siveton
              Reporter:
              Raphaël Piéroni
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: