Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Put documentation directly into the Piwik repository - better help pages in Piwik #9352

Open
tsteur opened this issue Dec 7, 2015 · 0 comments
Labels
c: Usability For issues that let users achieve a defined goal more effectively or efficiently.

Comments

@tsteur
Copy link
Member

tsteur commented Dec 7, 2015

Yesterday I was reading this blog post LEARNINGS FROM SWIFT BECOMING OPENSOURCE and one aspect was about documentation:

Swift has open source documentation ... its in the source tree. This is something I’d wish to see from MySQL ... or MariaDB ... but so far only Percona Server has gotten this right.

I thought about it for a while and it would make actually sense to have developer and user documentation in the source code. This would be quite a big project and can imagine that it's very likely not gonna happen (especially the user documentation) but I wanted to mention it anyway. With user documentation I was thinking about the user guides and FAQ from the website. It would be nice to find a way so Piwik.org builds the FAQ and user guides from the Piwik source code.

It would allow us to offer help within the Piwik UI with search etc (it would be possible to do this with Piwik.org as well but it wouldn't be the same). When common errors occur we could directly show the related FAQ article in the UI etc. It would also enable developers to directly read the documentation that matches their Piwik version in the IDE etc. We'd possibly get new FAQs, typo, fixes etc as Pull requests and we'd get a history (commits with diffs) of all changes, they would appear in the changelog automatically, etc.

Downsides are we would possibly lose some traffic to piwik.org (which should be less important compared to having a great, useful product though), it would require quite a bit of work especially for piwik.org website and we'd maybe want to find a way to auto-update the help articles in form of a plugin or so.

It would be really nice to have a nice help section in the Piwik app and to let people more likely find solutions to their problems and questions. As this is maybe not going to happen maybe we could alternatively discuss ways to integrate Piwik.org FAQ and user guides into Piwik UI in another way

@mattab mattab added this to the Mid term milestone Dec 23, 2015
@mattab mattab added the c: Usability For issues that let users achieve a defined goal more effectively or efficiently. label Dec 23, 2015
@mattab mattab modified the milestones: Mid term, Long term Dec 5, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c: Usability For issues that let users achieve a defined goal more effectively or efficiently.
Projects
None yet
Development

No branches or pull requests

2 participants