Hi Piwigo community members :-)
The current documentation on piwigo.org has several problems:
1) we're mixing "dev" and "user" documentation
2) the software (dokuwiki) is buggy in many ways and the look is really not as nice as we would like it to be
3) content is not up-to-date or complete
For now, I think we should move all "dev" related content to Github wiki. Developers use Github, that's the most relevant place in my opinion (+ when I see what teekay did for Bootstrap Darkroom, I really like it)
Now concerning the "user" documentation, I don't know yet what we should do. Community contributions are nice "but" if it leads to an everyday fight against spammers, it's not a good deal. I would like it to be beautiful, because we now have much higher standards when it comes to design :-) If you have suggestions, I'd be happy to read them!
Offline
I totally agree that the end user and dev documentations will gain being separated (even though if it is on the same platform).
Developper documentation
GitHub Wiki is good but rather limited, because it supports only basic Markdown and cannot be customized.
I really like vuepress (exemple https://photo-sphere-viewer.js.org/guide) it is mostly markdown, has a lot of plugins, and you can add Vue.js components if you need a bunch of interaction somewhere.
I recently discovered a theme for Hugo, but I didn't tested it : https://learn.netlify.app
User documention
I never wrote documentation for the "general public", so I don't know what would be the best tool...
Some static pages directly on the Piwigo plugin running the website ?
Or a dedicated vuepress/hugo/whatever ?
Offline
mistic100 wrote:
GitHub Wiki is good but rather limited, because it supports only basic Markdown and cannot be customized.
Can you give more details here? Where do you see we could feel limited?
mistic100 wrote:
Gorgeous. I love the design.
mistic100 wrote:
User documention
Some static pages directly on the Piwigo plugin running the website ?
A bit like what we did for requirements/install/update on https://piwigo.org/guides
It's obviously "doable" but it is also quite a lot of work in my opinion. Maybe once we have a general template, it would be the easiest solution indeed.
mistic100 wrote:
Or a dedicated vuepress/hugo/whatever ?
My feeling is that we need to be able to customize it. We need to be able to embed screenshots and videos.
Offline
> Can you give more details here? Where do you see we could feel limited?
as I said, because it only supports standard Markdown, it might be or not be a limitation, I know it is the reason I don't use it for Photo Sphere Viewer.
> My feeling is that we need to be able to customize it. We need to be able to embed screenshots and videos.
In a standard vuepress you can change the colors, but it is template based (vuepress in ensence is only the engine, and it comes with the default template I use on PSV) so you can do what ever you want.
Also any HTML can be added to the Markdown files, I use to embed jsfiddles.
Offline
executive wrote:
https://docs.gitbook.com/
nice service, definitely worth the try
Offline
Apparently gitbook.com is not free software and maybe not even open source (anymore, the legacy https://github.com/GitbookIO/gitbook CLI is dead since 3 years). Or I overlooked some hidden link. To me it seems it would be another vendor lock-in, even if the vendor might be nice people (now)(based in Lyon, France), though they do offer a free plan for open-source projects. And all data is stored in the Google cloud; well, encrypted, but.. furthermore in the US, so US legislation may be applicable for stored data, i.e. DMCA take down notices.
Offline
Piwigo shouldn't need to worry about DMCA, right? It doesn't really deal with copyrighted stuff.
Besides, laws are everywhere. And Europe probably has the most.
Offline
Oh really, Europe has laws? Remarkable discovery.
The point why I was writing that is, taking all together I would not choose the service for myself or a project I took care of. Closed source and data stored at Google, no thanks.
But as said, I'm not quite sure about the closed source, maybe it's just hidden and I didn't find it. If it's self-hostable it probably would be a good tool.
Offline
I my humble opinion you should keep any documentation efforts within the current piwigo site and not link anywhere else. And in France, thus subject to EU legislation and not hosted anywhere you risk other legislation to become a potential issue. Piwigo is French.
I have seen some system manuals written in Sphinx recently, seems like a very good platform for that, and looking at some of the manuals I have seen it has most if not all, possible markdowns and formatting options. You can also put it on your server where Piwigo is.
https://www.sphinx-doc.org/en/master/
Also has functions to migrate documentation in to the platform. Seems free/GPL/MIT but I find no specific license info available on its page...
Offline
plg wrote:
mistic100 wrote:
Gorgeous. I love the design.
It's VuePress: https://vuepress.vuejs.org/
Offline
Personally, I like creating documents in a word processor type interface, rather than writing code.
It might be overkill, but Wordpress has some plugins for creating documentation. Such as this one:
https://wordpress.org/plugins/wp-help/
Offline
executive wrote:
https://docs.gitbook.com/
I like GitBook too which is free for open-source & non-profit teams ;-)
Offline
Another https://v2.docusaurus.io/
Offline
ugh. I hate markdown.
Offline