Providing help on a website (basic CMS for on-site site documentation)

[Bernd Wechner]

I'm at the point of wanting to write some help for a website, the standard helpfile sort of scenario ;-). If that means little to you, just a hierarchy of pages that document things and can be linked.

I wrote page one with the Django flatpages app:

https://docs.djangoproject.com/en/2.1/ref/contrib/flatpages/

But it's not real comfy in terms of editing and maintaining. So I looked on-line for solutions and of course nothing with "help" in the search terms is going anywhere fast (finds me a lot of help about Django ;-). so better keywordss needed but I have found a pile of maybe options and am suddenly bamboozled by what is vogue, current, maintained, has a lasting future etc.

https://github.com/klen/django_markdown

Untouched in 4 years with 22 open issues Hmm.

And this looks nice:

https://github.com/mjr27/django-flatpages-tinymce

but untouched in 7 years and 4 open issues.

Now untouched doesn't mean bad, could just be mature, stable and works perfectly, already fro 7 years. These are the things it's hard to gauge. But if I'm looking at TinyMCE how about:

https://github.com/aljosa/django-tinymce

on which it depends. NO bad, updated a month ago to make it work with Django 2.1 so seems alive! But my site is math heavy so I want equation ease so how about:

And this looks good:

https://www.codecogs.com/latex/integration/tinymce_v3/install.php

This looks maybe:

https://github.com/iCAPLyon1/tinymce-formula

This looks unconvincing:

https://github.com/foraker/tinymce_equation_editor

and do we want this:

https://github.com/Tivix/django-flatpages-nav

or this as well:

Or hang on why do this piecemeal why not use Wagtail from the word go:

http://docs.wagtail.io/en/v2.4/index.html

Or would wagtail introduce too much coordination trouble between its templates and my sites ... etc. etc. I'm full of questions and really just wondering, is there a canonical solution to a site documentation page hierarchy and managing it nicely?

Regards,

Bernd.

[Bernd Wechner]

Hmmm, no-one has any thoughts here ... and I'm on ma' own reinventing the wheel? Surely tehre's a canonical way to provide help on Django website . I'm leaning toward simple flatpages app with a tinymce editor for them for the admin.

[RLM]

Sorry to go off topic but I can recommend HuGo for simple markdown web pages.
Cheers
Roger

--
You received this message because you are subscribed to the Google Groups "Django users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-users...@googlegroups.com.
To post to this group, send email to django...@googlegroups.com.
Visit this group at https://groups.google.com/group/django-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-users/750a97d8-87f9-42f4-997e-5810e1a5c48a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Bernd Wechner]

Can you offer a link to HuGo?

Not entirely off-topic. I'm fishing for what people do here. Surely it's a ubiquitous need. But I wrote one flatpage following a Django tutorial but it's a nightmare to maintain as it's just a blockof HTML in a fiueld in the admi interface, aaargh, there must be a canoncial way fo managing a hierarchy of flat pages that provide help or FAQs or such for a website.

[Christo Kriegler]

Hi Bernd

I don't know if you can find something here https://www.quora.com/Django-web-framework-What-is-the-point-of-using-flatpages, just maybe you read something you looking for.

Blessings

Christo

[Derek]

"Surely it's a ubiquitous need"

No, I think not. In the dim and distant past I used to write copious help files for various Windows apps ... but on the web?  No one really reads manuals or help files any more - your app needs to be simple and obvious to use.  

If you are that noble as to still want to write a manual, I'd suggest using any number of really good off-line tools and make the manual downloadable as a PDF - most of those tools will also generate a series of static webpages which you can host quite easily.   Suggestion: ReadTheDocs uses Sphinx to generate docs for Python libraries; but there is no reason you could not also use that to write end-user documentation.

HTH.

[Bernd Wechner]

Derek,

Empirically by evidence of the lack of material on-line or obvious solutions, you may be right. But I respectfully disagree. Almost every website has an About Us page for example and a pile of other simple flat pages.

And Django supports flatpages natively, just not with a well documented easy way to edit them easily!

Regards,

Bernd.

[Derek]

Bernd 

Data-driven sites, such as the ones that Django is very good at developing may have one or two "about" type pages but they do not typically do have "a pile" of other flat pages.  Such websites are usually not developed in Django but rather in a CMS-type application.

Unfortunately, you seem to be in some less-common "middle ground" where you need both a pile of flat pages and a pile of dynamic pages.... a chance for creativity on your part!

[Bernd Wechner]

Derek,

Not quite. I don't heaps at all. An About Page, a FAQ page, a Help page ... that's about it. It still sucks to high heaven to try and edit these HTML pages nicely in an external app, and then have to paste the HTML into a Django Admin box where the flatpage is stored. Surely, I imagined, there is a canonical solution to managing even 3 such pages without going through such a nutty routine. And given I think there is a TinyMCE plugin that lets you edit flatpages in a TinyMCE box ... like much easier, I figured I might hear from someone with a similar experience and who's solved it in a comfortable way. But apparently not. Quite an eye opener! And yes, maybe they use a CMS and if so, is there a canonical Django compatible approach in that space ... Wagtail suggests itself, but could well be major overkill of a handful of info pages.

I do remain deeply surprised that this is not a fairly ubiquitous issue. I mean does anyone find Django flatpages easy to maintain (edit)?

Regards,

Bernd.