Announcement

  •  » Website
  •  » Documentation needs a serious refresh

#1 2020-11-23 10:29:44

plg
Piwigo Team
Nantes, France, Europe
2002-04-05
13786

Documentation needs a serious refresh

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

 

#2 2020-11-23 13:23:14

mistic100
Former Piwigo Team
Lyon (FR)
2008-09-27
3277

Re: Documentation needs a serious refresh

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

 

#3 2020-11-23 13:41:12

plg
Piwigo Team
Nantes, France, Europe
2002-04-05
13786

Re: Documentation needs a serious refresh

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?

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

 

#4 2020-11-23 14:07:48

mistic100
Former Piwigo Team
Lyon (FR)
2008-09-27
3277

Re: Documentation needs a serious refresh

> 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

 

#5 2020-11-23 21:54:39

executive
Member
2017-08-16
1214

Re: Documentation needs a serious refresh

Offline

 

#6 2020-11-23 22:17:43

mistic100
Former Piwigo Team
Lyon (FR)
2008-09-27
3277

Re: Documentation needs a serious refresh

executive wrote:

https://docs.gitbook.com/

nice service, definitely worth the try

Offline

 

#7 2020-11-23 23:49:50

erAck
Only trying to help
2015-09-06
1998

Re: Documentation needs a serious refresh

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.


Running Piwigo at https://erack.net/gallery/

Offline

 

#8 2020-11-24 02:44:14

executive
Member
2017-08-16
1214

Re: Documentation needs a serious refresh

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

 

#9 2020-11-24 11:42:40

erAck
Only trying to help
2015-09-06
1998

Re: Documentation needs a serious refresh

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.


Running Piwigo at https://erack.net/gallery/

Offline

 

#10 2020-11-24 12:10:37

homdax
Member
Sweden
2015-02-02
294

Re: Documentation needs a serious refresh

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

 

#11 2020-11-24 12:15:47

homdax
Member
Sweden
2015-02-02
294

Re: Documentation needs a serious refresh

plg wrote:

Gorgeous. I love the design.

It's VuePress: https://vuepress.vuejs.org/

Offline

 

#12 2020-11-24 22:24:45

executive
Member
2017-08-16
1214

Re: Documentation needs a serious refresh

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/

https://ps.w.org/wp-help/trunk/screenshot-1.png?rev=2193329

Offline

 

#13 2020-11-30 15:19:04

cryopad
Piwigo Team
Grenoble, France
2015-11-01
190

Re: Documentation needs a serious refresh

executive wrote:

https://docs.gitbook.com/

I like GitBook too which is free for open-source & non-profit teams ;-)


If you enjoy Piwigo for iOS…
➤ We would appreciate an AppStore review.
➤ Comments, suggestions ? Tell us on GitHub…
➤ Not yet available in your language ? Help us translate it…

Offline

 

#14 2020-12-16 22:27:24

mistic100
Former Piwigo Team
Lyon (FR)
2008-09-27
3277

Re: Documentation needs a serious refresh

Offline

 

#15 2020-12-16 22:47:27

executive
Member
2017-08-16
1214

Re: Documentation needs a serious refresh

ugh. I hate markdown.

Offline

 
  •  » Website
  •  » Documentation needs a serious refresh

Board footer

Powered by FluxBB

github twitter newsletter Donate Piwigo.org © 2002-2024 · Contact