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
  • [x] #61 The Javascript Tracking Client
  • [x] #41 Tracking API Clients
  • [x] 60b521d2e6424654a6613537754fc76609efb739 All About Tracking
  • [x] #65 Content Tracking
  • [x] #66 Reporting API Tutorial: Get your top 10 keywords
  • [x] #66 Querying the Reporting API
• Develop
  • [x] #25 Getting Started Part I
  • [x] #26 Getting Started Part II
  • [x] 97ad26c390b Getting Started Part III
  • [x] #49 Distributing Your Plugin
  • [x] #32 How Piwik Works
  • [x] #64 All About Analytics Data
  • [x] #60 Piwik's Extensibility Points
  • [x] b94d9c6b8b5f MVC in Piwik
  • [x] #48 Pages
  • [x] #48 Menus
  • [x] #48 Widgets
  • [x] #69 JavaScript and CSS
  • [x] #59 Visualizing Report Data
  • [x] #43 Piwik INI Configuration (moved as sub-article of Piwik Configuration)
  • [x] #43 Piwik Configuration (extracted "Plugin Settings" into sub-article)
  • [x] #43 Plugin Settings
  • [x] #56 Persistence & the MySQL Backend
  • [x] #36 Security best practices
  • [x] #48 Permissions
  • [x] #37 Internationalization
  • [x] #38 Tests
  • [x] #63 Piwik's Reporting API
  • [x] #50 Scheduled tasks
  • [x] #52 Piwik on the Command Line
  • [x] #53 Contributing to Piwik Core
  • [x] #30 Core Team Workflow
  • [x] #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!