Use of Kuma for other documentation than MDN

MDN
#1

Hi, we are currently setting up an instance of Kuma to use it for our own open source project documentation. I was wondering about a couple of things:

  • has anybody else done that (probably)
  • is there a reasonably workable way to include our internal documentation in the same instance, and e.g. make some wiki documents only readable/editable for certain groups

Kind regards from southern Norway,

Thomas

PS. I did try a couple of searches like private, internal, 403… but without real results. I have looked into how Jinja is set up and think this should be doable… just wondering of anybody our there has a good way on how to proceed without screwing up the system :wink:

1 Like
#2

You might want to ask @jwhitlock or @fscholz.

1 Like
#3

Thanks, so @fscholz and/or @jwhitlock, do you have any input on this? Could this be doable by a group and a couple of template changes with hardcoded group names?

#4

Theoritically its surely possible but to say in practical, there are a lots of features which are hardcoded specific to mozilla. Kuma is not general purpose wiki software (still now).
Better you can use other wiki software like MediaWiki and others.

#5

We are developing what we call the operating system for the internet - so we are a bunch of web engineers and really see Kuma being made for web documentation for web technologies a huge advantage of it over other solutions :slight_smile: I have come quite far with our adoptions, and for the public part of the documentation we are ready to go - its just the internal part that we have yet to figure out.

#6

Thats great that you could make the changes and adopt kuma for your usage.
For your second point,

  • is there a reasonably workable way to include our internal documentation in the same instance, and e.g. make some wiki documents only readable/editable for certain groups

Its possible if you know a bit of python and django. You can edit this view and add a permission about certian document, so its viewable by only the user which have that permission. Doing like this, I think you can also figure out how to do with edit and others! :wink::wink::wink::wink:

2 Likes
#7

I really want to allow our staff developers to create documents and give them a way to mark them as internal - reviewing the whole architecture I think that maybe even a Kumascript macro could do the trick. Don´t really want to change the python script if I don´t have to.

#8

I do not think you can change the kumascript only and make them internal.
So what you can do

  • Add a boolean field in the Document model
  • Change the queryset according to the flag in view and other place
#9

Small update here: I did only change template files and added a custom navigation section wrapper in a {% if user.is_staff %} - and then changed document.html at the document_head and content block with

{% if not ( ( 'OURSECRETINTERNALURL' in document.slug and user.is_staff ) or ( 'OURSECRETINTERNALURL' not in document.slug ) ) %}
		<!-- accidental access to an internal page... -->
		<p>This content is not available at the moment. Please <a href="/">start over</a>.</p>
	{% else %}
....
{endif}

It might not be the most secure way as I have to make sure search index will respect that “setting” - but for now it does the trick - main reason for having an internal section is to document stuff and not get arrested by externals for breaking changes at some point.

#10

The original plan way back when was for Kuma to be generally usable, and we even used to talk people up about that, early on in its life. But technological demands and the realities of project management with resource constraints have led to that becoming less and less practical as more MDN-specific stuff is built straight into the software.

I still wish we’d been able to stick to that original goal, but our needs outweighed our ability to get things done in a flexible way.

2 Likes
#11

I don’t recommend using Kuma as an internal documentation engine. It’s built for the needs of MDN, not as a general purpose wiki engine. It hasn’t kept up with the evolving mission of MDN, so I can’t wholeheartedly recommend it for MDN either.

MDN doesn’t support restrictions on reading or writing content, and assumes all content is world readable and writable. There is an open bug to add access control for editing (bug 768498), open for 6 years without action. My guess is that a feature like that will be challenging to implement completely, leading to bugs and access violations. It is something that is best designed from the start, not bolted on later.

Over ten years ago, I used MoinMoin as an internal company wiki engine, and it worked well. I also wrote 99% of the content, and wasn’t able to convince others on the team to embrace the wiki lifestyle. I believe content creation is the biggest problem, not the engine.

Today, I would recommend trying the wiki feature on GitHub: https://help.github.com/articles/about-github-wikis/. You can add a wiki to a private repository to restrict read access, and editing is restricted to project collaborators.

1 Like