Review each guide and improve the content and structure

[mattab]

The goal of this project is a medium term goal that you review each page of the Developer website. The goal is to make the documentation from OK quality to good or even very good (!) when possible.

Project description:

• Docs to review: https://github.com/piwik/developer-documentation/tree/master/docs
• There are about 40 pages some of them maybe un-necessary, some can be improved, some could be maybe merged or split.
• Good resource: http://jacobian.org/writing/great-documentation/

See also the related issue in piwik/piwik

Assigned to at least @mnapoli and @mattab who will review content of each page

• Integrate
  • Reviewed "The Javascript Tracking Client" #61 The Javascript Tracking Client
  • Remove duplicate Tracking API user guide  #41 Tracking API Clients
  • 60b521d All About Tracking
  • Reviewed the "content tracking" guide #65 Content Tracking
  • Reviewed the reporting api guides #66 Reporting API Tutorial: Get your top 10 keywords
  • Reviewed the reporting api guides #66 Querying the Reporting API
• Develop
  • Improvements on "Getting Started Part I" #25 Getting Started Part I
  • Improvements on "Getting Started Part II" #26 Getting Started Part II
  • 97ad26c Getting Started Part III
  • #22 Reviewed "Distributing Your Plugin" #49 Distributing Your Plugin
  • Added the "How Piwik Works" guide #32 How Piwik Works
  • New section about "Data Model" #64 All About Analytics Data
  • Reviewed "Piwik's extensibility points" #60 Piwik's Extensibility Points
  • b94d9c6 MVC in Piwik
  • #22 #44 Article reviews and migration #48 Pages
  • #22 #44 Article reviews and migration #48 Menus
  • #22 #44 Article reviews and migration #48 Widgets
  • Reviewed Javascript and CSS #69 JavaScript and CSS
  • Reviewed the "Display Reports" guide #59 Visualizing Report Data
  • Reorganization and redesign #43 Piwik INI Configuration (moved as sub-article of Piwik Configuration)
  • Reorganization and redesign #43 Piwik Configuration (extracted "Plugin Settings" into sub-article)
  • Reorganization and redesign #43 Plugin Settings
  • Reviewed and splitted the persistence guide #56 Persistence & the MySQL Backend
  • Reviewed Security In Piwik #36 Security best practices
  • #22 #44 Article reviews and migration #48 Permissions
  • Reviewed "Internationalization" guide #37 Internationalization
  • Reviewed "Automated tests" #38 Tests
  • #22 Reviewed Piwik Reporting HTTP API #63 Piwik's Reporting API
  • #22 Reviewed "Scheduled Tasks" #50 Scheduled tasks
  • #22 Reviewed "Piwik on the Command Line" #52 Piwik on the Command Line
  • Reviewed "Contributing to Piwik Core" #53 Contributing to Piwik Core
  • Review of the core team workflow #30 Core Team Workflow
  • Reviewed and split the Theming guide #70 Theming

[mattab]

Here is some feedback after your nice PR was merged @mnapoli

• Not sure about the new <code> style it looks too light maybe? before was high contrast which is useful eg tracker api
• when looking at a given guide or reference, the top left menu API Reference should collapse and can be expanded on click (regressed) - it's useful as it helps user focus on current page
• http://developer.piwik.org/api-reference/tracking-api we can remove the from title
• on http://developer.piwik.org/api-reference/events#assetmanagerfiltermergedjavascripts there are un-renmarkdown links eg. [Period](/api-reference/Piwik/Period)
• rename http://developer.piwik.org/api-reference/PHP-Piwik-Tracker to "Tracking API PHP client" ?
• rename page http://developer.piwik.org/api-reference/reporting-api to 'Reporting HTTP API`
• Somehow this page: http://developer.piwik.org/guides/tracking-api-clients would be great to have also below Tracking HTTP API in http://developer.piwik.org/api-reference/tracking-api - it's awkward to have pages twice on the site but i see great value to list all tracking clients & SDK prominently in our Reference section...
• add some space between two blocks in left menu
• The website seems to load quite slow sometimes, not sure if it's due to some change or my internet connection...

[mnapoli]

• rename http://developer.piwik.org/api-reference/PHP-Piwik-Tracker to "Tracking API PHP client" ?

Definitely agree, but it doesn't seem to be easily doable because it's the generated documentation: the name is the name of the PHP class. I don't see how to do that without changing a lot of things :(

[mnapoli]

The website might be slow when the cache is cleared: to build the left menu (and keep the code simple) we have to be read all guides of the category, which is quite fast (even though it's theoretically inefficient) but in some case it includes a remote URL so it takes a bit of time. I went that way because online everything is cached so it's not an issue once a page is viewed (and it makes the whole code much easier).

We could add a warmup after clearing caches if that's too critical.

[mattab]

We could add a warmup after clearing caches if that's too critical.

it's not critical, it's pretty fast for now, but if warmup is very low effort for you then +1 ;-)

[mnapoli]

Once #70 is merged this task is finished!

[mnapoli]

Done!

[mattab]

Plugin developers now have a great resource to learn from, and @piwik/core-team will keep iterating and updating the guides as the platform evolves.

Well done!