Closed mattab closed 13 years ago
Attachment: 1st (unfinished) draft Introducing Piwik 1.0.doc
Attachment: Screenshots for rIntroducing Piwik 1.0 img.zip
Attachment: Notes on Introducing Piwik.txt
Attachment: I remade all screenshots in high quality PNG format, except for the ones in the improving folder. I didn't manage to create campaigns :( img-png.zip
Attachment: zip file with screenshots of all core widgets, taken on 2010-08-18 widgets.zip
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:
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?
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 #5600
That might be a good one to start with, what do you think?
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.
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 :)
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!
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:
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 metricsa 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.
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
Answers to your notes
See #1382
Agreed, but text a bit long, it might not fit. What about 'Email reports'?
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?
Thanks Greg for updated screenshots!
idw, do you have any update on the user documentation?
I merged the work done by idw in piwik.org documentation. Also thanks Greg for the screenshot.
What I haven't put online:
New doc pages:
Updated pages:
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 :)
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:
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:
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.