Showing content from https://github.com/pmd/pmd/issues/791 below:
[doc] Documentation site reorganisation · Issue #791 · pmd/pmd · GitHub
I think our documentation site could a clearer structure:
- User documentation mixes things about using PMD and trivia about PMD.
- Developer documentation mixes things about making rules (like we encourage our users to), extending PMD by adding languages/ metrics framework (clearly something not all rue developers are up to), and information for PMD committers (eg making releases), which concerns even less people.
All of that makes it unclear to whom the content of each page is addressed (harder to write), and makes it harder for anyone to find what they're looking for. Specifically, I think we should try to address separately different types of readers, and reflect that in the structure:
- Users who only want configuration (understanding rulesets, making their own, using properties)
- Users who want extensibility (writing XPath and Java rules, defining properties, testing rules). These one don't necessarily want to know about building PMD from source or our Checkstyle guidelines, unlike...
- Users who'd like to contribute to PMD (they should find info about PR-making interesting). Again, not all of them would like to know about adding a whole new language, but some would.
- PMD committers, who're probably the only ones interested in technical info about merging PRs or releasing
In comparison, I find Checkstyle's website is really well organised and easy to navigate. Taking that into account, I propose the following reorganisation of the existing documentation pages. Please leave comments ;)
New documentation structure About
- Userdoc/Introduction
- Userdoc/Release notes
- Userdoc/Getting help
User documentation
- Userdoc/Getting started
- Userdoc/Understanding rulesets
- Devdoc/Making rulesets
- Userdoc/Best practises
- Devdoc/{Working with properties (first half) => Using properties}
- Userdoc/{Suppressing => Suppressing warnings}
- Extending PMD (softcore) // Custom rule making
- Understanding the AST // doesn't exist yet
- Devdoc/Writing XPath rules
- Devdoc/Writing a rule
- Devdoc/{Working with properties (second half) => Defining properties}
- Devdoc/Using code metrics
- Devdoc/Rule guidelines
- Devdoc/Test framework
- Userdoc/Copy-paste detection
- Userdoc/Tools + integrations
- Maven PMD plugin
- Ant
- Other tools
Rule reference // doesn't change Developer documentation // specifically oriented toward contribution
- Devdoc/Developer resources
- Devdoc/Setting up your IDE // merge with devdoc/Building PMD from source
- Devdoc/{Pull requests (half about making PRs) => Contributing} // merge with devdoc/Code style
- Devdoc/How PMD works (merge with Devdoc/Architecture)
- Extending PMD (hardcore)
- Devdoc/Adding a new language
- Devdoc/Adding a new CPD language
- Devdoc/Adding metrics support to a language
- Devdoc/Roadmap
Language-specific documentation // doesn't change Project documentation
- General information
- Trivia about PMD
- Userdoc/PMD in the press
- Userdoc/Products + books
- Userdoc/Similar projects
- Userdoc/What does PMD mean?
- Userdoc/Credits
- Userdoc/License
- Userdoc/Old release notes
- Project management // info for committers mainly
- Devdoc/{Pull requests (part about merging) => Merging PRs}
- Devdoc/Releasing
RetroSearch is an open source project built by @garambo
| Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4