Piwik user documentation proposal

[matt]

Piwik doesn't currently provide a complete user documentation. The current documentation pages cover specific topics such as: Installation, Upgrades, Javascript Tracking API, and a good set of FAQs.

While we already have a few  specific tickets for user documentation, we do not yet have a general plan of what the Piwik user documentation should be.

Here is the Piwik user documentation proposal.

User documentation

The user manual at http://piwik.org/docs/ would contain all the generic Piwik help. I think it is best to keep the number of pages low and have each page describe several related features. The page http://piwik.org/docs/ would be a table of contents linking to the doc pages. This page could also be linked from an "Help" link in the top bar in product.

List of docs to cover the main Piwik use cases:

• Understanding the Actions reports tips on how to track pages properly, Page URLs vs Page names, tracking downloads and outlinks.
• Understanding the Referers reports direct entry vs SE vs website explained, how to track campaigns (link to the URL builder tool that we can easily create) see ticket #604, how to tell which referring segments are most successful
• Understanding Goals in Piwik how to create a goal, lists the reports given for a goal (segmentation by referer, country) - see ticket #616
• Users Management you can add unlimited number of users, how to add a user, change permissions, change user password/email, etc.
• Website Management you can add unlimited number of websites, how to add a website, edit website settings, etc.

For each of these pages, we will explain what the reports data mean, and provide one or several examples on how it can be used to improve your website performance.

We can also provide some advanced help:

• Advanced tracking How do I track Flash events, JavaScript events, banner ad exits, AJAX applications, how to track forms? ( example GA)

• Using Piwik with several domains and directories How to track a 3rd-party shopping cart, track all of the subdomains for my site in one website, how to install the tracking code if my site spans multiple domains, how to track all of the subdomains for my site in separate websites, how to setup tracking for multiple domain names/ domain aliases, How do I track unique areas within my website separately? ( example ga)

• Using Piwik to track Adwords - see ticket #517

Documentation example

Each documentation page would contain a few screenshots showing the related UI sections, one or more real life examples (use cases). See the page:  how to submit a new documentation to Piwik?.

The documentation footer would contain a call to edit (did you find a mistake in the documentation? is the documentation not clear? Send an email).

FAQ

We currently update the FAQ pretty regularly with new questions and updates to existing questions. The FAQ is a very useful knowledge base, and we try to put all questions asked at least twice in the forums in the FAQ.

This FAQ could be completed to describe terms and vocabulary used in Piwik (bounce rate, returning visits, new visits, conversions, etc.). We currently have a few basic vocabulary in http://piwik.org/faq/general/

Conclusion

Any thoughts about this proposal?

If you can write clear and good English, if you are using Piwik and want to participate in the project with writing user documentation, please contact us; we are actively looking for writers! Contributing even one page would be great.

[idw]

Hi, I'm new around here. Very excited to be learning about piwik. So this is just a thought but (perhaps in the longer term) floss manuals might have something to offer. What CiviCRM has done with them is a brilliant manual:  http://en.flossmanuals.net/civicrm and their idea of book sprints might have something to it. What I love about CiviCRM's manual is you can print it off, read it from cover to cover, it's not a painful read and at the end you feel like you really understand what CiviCRM can do for you and that it wouldn't be too hard to make it work.

As to structure, I think there's a danger of being technology-centred rather than reader-centred. There's a page on /docs at the moment which is, more or less, everything-you-can-do-by-modifying-the-javascript. It is really well written and useful, but I suspect it's not how end users think about what they're trying to do?

I suppose you have to decide whether the goal is to make sure that everything in piwik is documented, or whether the goal is to make sure that there are docs that, even if they only walk people through 2/3 of what piwik can do, do that in a really simple engaging way for new users. I think both are necessary, but I think the latter is the one that will help piwik grow more: once people are in they are more willing to wade through the site to learn how to do even more.

For comparison, I pulled up the ToCs for the top two GA books on google:  http://www.amazon.co.uk/gp/product/toc/0470053852/ref=dp_toc?ie=UTF8&n=266239  http://www.amazon.co.uk/gp/product/toc/0470253126/ref=dp_toc?ie=UTF8&n=266239

I'd suggest something like this:
- Introduction to analytics
- Getting started with Piwik (What you can do out of the box/on the demo site)
- Installing and Configuring Piwik in 5 Minutes
- Using plugins
- Using Piwik to improve your site (goals, campaigns etc.)
- Customising Piwik (overview of API and pointer to dev docs)
- Glossary

At least the first three already exist in the docs/presentations/blog and stuff. I just think (potential) new users like me will find it really useful to see it presented in one coherent form with lots of reassuring screenshots.

Way more than my 2p, I know, but I'd be happy to help within my very limited time budget, if there was a consensus around what needed doing.

ps- just found this:  http://dev.piwik.org/trac/wiki/UserGuide/Roadmap ... maybe should reference this issue/vice versa?

[matt]

idw, your outline proposal sounds great. I would maybe just remove "- Using plugins" as really by default, plugins are not necessary to use Piwik: all main plugins are enabled by default.

I think the biggest missing one is "What you can do out of the box", a list of features that would really explain the main possibilities of Piwik,and link to more details when available. See #180

That might be a good one to start with, what do you think?

[eset]

adam here from FLOSS Manuals - we are happy to help if we can. I love Piwik...we used it for a while tracking stats on FM. But I stopped because essentially i think the idea of stats guiding manual development isnt the right approach (but I still love Piwik :)

if you want to go forward with a manual in fm let me know. we can set up a manual quickly.

[matt]

I think that stats guiding the user manual is a very strong and efficient approach especially using search Analytics (search without results, search refinement, search exits, etc.) which show what information users are seeking and how the manual can help them. But Piwik doesn't do that well... yet :)

[idw]

I can't see a way to change the issue ownership, but I'm adopting it for a day ;-)

Really nice of adam to pop up like that!

[idw]

1st (unfinished) draft

[idw]

Screenshots for rIntroducing Piwik 1.0

[idw]

Attached is a first stab at pulling together a manual. About 50/50 new and existing, but with everything edited for consistency (language use, expectated reader skill level) and with updated screenshots.

It has 8 sections:
* What is Piwik?
* Features
* A Tour of Piwik
* Installing
* Using Piwik to Improve your site (Campaigns and Goals)
* Sharing Your Piwik Analytics (Adding users, Email reports, Embedding)
* Customizing (API, Plugins, Developing)
* Glossary

Goals still needs editing and its screenshots updating. Other than that, all sections are good to go except the Tour. In that, Dashboard is done, Visitors, Actions, Referrers still to do (i.e. a guide to all the metrics—a pretty substantial job).

My target has been an 80% or 'good enough' document. It's good enough to stand on its own. There are lots of ways it could be better (most urgently the Features section) but get the rest of the tour finished and it'll be a decently credible manual.

The biggest thing has been pitching it at the right level. This is principally aimed at end users. As a rule of thumb, anything beyond the point and click interface I've left out, with one or two exceptions (Campaigns URLs comes to mind). There is definitely room for an 'Advanced Piwik 1.0' manual, but just having the How Tos on the website covers the techie crowd pretty well, I think.

At the end of the Notes doc is a bunch of thoughts I had on things that confused me while going through Piwik pretty thoroughly, which may or may not warrant turning into issues.

[matt]

idw, Great start of user doc. This is a significant improvement. It will help Piwik users be a lot more comfortable in finding out and using existing feature set.

I read through the doc and here is feedback

• Date range: custom date range is not possible yet, so date picker won't change before V1. It might in 1.x when we introduce custom date range #572
• Screenshot quality appears poor (pixelated). I think this is because they are JPG. Maybe we could have high quality screenshots in PNG in the manual?
• Widgets screenshots: when making screenshots of widgets, maybe increase screen resolution to at least 1280x so that widgets are more readable (eg. Page 4 Visits by server time is a bit narrow)
• How would you map the manual to website pages? Original idea was that the index docs page http://piwik.org/docs/ would act as a table of contents to the various doc pages. Do you think this will work nicely?

Answers to your notes

• I created a ticket with your usability feedback at #1556 - feel free to comment there for other usability feedback :)
• If we get a manual agreed there ought to be some process of checking the manual is update to date before each release... the installation has changed but the guide hasn't

It's up to each Piwik core developer/team member to ensure that each new code comes with i18n, unit tests, good usability, updated documentation. Of course other devs will review commits to ensure that new feature / bug fixes are updated in the doc. The  dev doc also mentions "When applicable, the related online documentation and the related FAQs should be updated.

• The JavaScript Tag page on stage 8 of the install is massively overcomplicated. It's basically trying to make up for the lack of a manual. The page should simply say here's your tag, and everything else should be in a manual somewhere under Advanced Piwik-most people will never need to know.

I think it's important that the UI shows most features that are available. If we only advertise a feature in the doc, most users will never discover it. I agree current UI is a bit complicated and geeky but we can improve it (any idea?) instead of removing it all from in product screens.

• Surely "How to install Piwik.html" has no place? A URL in README would suffice.

this file has been helpful. A lot of users don't read README files, but would open the .htm in their browsers after unpacking the files. We have  a lot of direct entries on the install doc page (100 entries on this page yesterday for example) which shows that this file is probably used.

• Are search engine spiders excluded?

This is clarified in http://piwik.org/faq/new-to-piwik/#faq_63

• The Add user UX is clunky. The table turns into a form, no warning of password constraints, no obvious submit button... you have to guess that you're meant to press Edit to save.

See #1382

• PDF reports is a great feature, that GA makes horrible to use. Deserves a better flag than 'PDF'. Similarly the title to that page... 'Manage Email Reports' would be more friendly.

Agreed, but text a bit long, it might not fit. What about 'Email reports'?

• Inconsistent use of confirmation messages (e.g. none when you create a new PDF report), exclamation marks sometimes not always. Low priority good to agree a standard to work towarads.

where is the inconsistency? I didn't think we ask for confirmation when adding or editing stuff, only when deleting objects?

Should we now create pages for "Manage Users", "Manage Websites", "Using Dashboard", etc. ?

This is a great start - how do you want to proceed from there?

[greg]

I remade all screenshots in high quality PNG format, except for the ones in the improving folder. I didn't manage to create campaigns :(

[greg]

zip file with screenshots of all core widgets, taken on 2010-08-18

[matt]

Thanks Greg for updated screenshots!

idw, do you have any update on the user documentation?

[matt]

I merged the work done by idw in piwik.org documentation. Also thanks Greg for the screenshot.

What I haven't put online:

• How Piwik works
• Features (not finished)

New doc pages:

• Piwik Tour
• Manage users
• Manage Email reports
• Embed Piwik in websites or apps

Updated pages:

• How to install piwik
• Goals tracking

Thanks idw for your work, very appreciated and great content!!

Marking as fixed and will create another ticket with the missing doc since there is lot less now :)