Documentation writers wanted!

[arkascha]

Branch 'master-doc' (https://github.com/arkascha/owncloud-shorty/tree/master-doc) implements a "help" icon instead of the existing "home" icon in the top control bar. It opens to a "documentation center" (or whatever" in a separate window where some bundled documents are displayed. I do agree with the general owncloud idea, that things should always be that easy and intuitive, that an additional help documentation is not required. However looking at my experiences with for example the setup of the static backend I have to admit that Shorty probably cannot fulfill this idea.

Currently I still tell people there are documentation files bundled, but that does not really make sense, since you cannot see them except when opening the file system. So why not showing them in an explicit manner?

I am currently still trying to enhance the navigation, but another task that is still open in this is enhancing the content of those documents. Since I often see people willing to contribute, but claiming that coding is not their thing I thought: wham! That's it! Everyone can participate here! :-)

So... anyone want's to give it a try? Perfect opportunity for collaboration!

[arkascha]

cc: @chadrien @fredl99 @vgezer @turnerd10 @LEDfan @redhell @nickvergessen @simonbuehler @chakphanu @turgo @DavidStaron @Signum @GamesGamble

[fredl99]

I would be willing as time permits. But where to go and what to do?

[arkascha]

@fredl99 That is great! Welcome! I granted you collaboration permissions to https://github.com/arkascha/owncloud-shorty/tree/master-doc Note that this is my private fork you already know, since I do not have the permissions to grant permissions for the owncloud repositories. I suggest to work on the documentation there and then create a pull request once the documents appear to be ready to be integrated.

[fredl99]

there are documentation files bundled, but that does not really make sense, since you cannot see them except when opening the file system. So why not showing them in an explicit manner?

Hm, why not make use of Welcome to the shorty wiki:

Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together.

Just a thought. You wouldn't have to create, maintain and ship code to people who might either not need it or know how to open a textfile for reading. The Wiki offers collaboration functions, version control, and is available to the public even before installing the software. I also think documentation writers could find it more convenient to work with a Wiki than in a coder's environment. ;)

Only my 2¢

[arkascha]

Users do not have to find and open text files, instead the branch implements a "documentation center" (which is not app specific btw). You reach it using the help button at the top right (the question mark). The documents offered in there are the text files in the apps folders. And they are not plain text files, but markdown, just like the github wiki pages. I bundled a small, extremely simple markup interpreter: SlimDown (https://gist.github.com/jbroadway/2836900)

So all markup notations in the documentation files will be interpreted and converted to beautiful html on-the-fly. Until now the files were plain text files, I just started reformatting them when I realized that this might be an interesting opportunity for others.

[fredl99]

The documents offered in there are the text files in the apps folders.

Makes sense. That's why I initially thought about implementing a kind of "permanent Shorty" to them. The path should be easy to find out, and for navigation a simple index-file would be sufficient as the target.

they are not plain text files, but markdown

So they could be placed into the Wiki here in parallel. If only to have a bigger audience.

And to answer my first question:

But where to go and what to do?

I suppose, it's about editing the files within the doc-folders in https://github.com/arkascha/owncloud-shorty/tree/master-doc/*/doc: installation, configuration, usage and readme?

[arkascha]

Ah, sorry, completely missed that question yesterday. Sorry, my fault. Indeed, the idea would be to work on the collection of those documentation files. That means:

• what files are required finally?
• how should content be divided onto these files?
• the actual content (currently text format) must be changed to markdown / slimdown syntax
• missing stuff must be documented
• linguistic corrections to make things easy to understand
• defining what chapters to contain in what books
• finding a way to offer books/chapters depending on the users group (for example admin group)
• defining a "book" inside the implementation to know what documentation files to offe rin what book, in which order and under what name.

Note that such documentation files also exist within the plugin(s) to Shorty (currently only the Tracking plugin): https://github.com/arkascha/owncloud-shorty/tree/master/shorty_tracking/doc

The current implementation thinks of "books" containing "chapters". Here each app can register books in the documentation center, Shorty registers two: a user guide and an admin guide, the tracking plugin registers a third, the tracking guide. more might follow, especially with additional plugins getting implemented. This is because those plugins (at least Shorty Tracking) do not offer an own menu entry or the like. So their documentation must somehow be bundled with the main app, without confusing those users on ownClouds where the plugin is not installed.

[fredl99]

A bundle of doc files is now converted into markdown syntax. These are available in the new directory ./doc/en/ (To be prepared for later translations into other languages) The code for the help center now reads and presents (some of) the markdown pages instead of the former plain-text files. This part of the project is by far not finished, but now we have a fair amount of data to evaluate and decide how to proceed.

Unfortunately slimdown interprets some of the formatting options a bit different than the markdown documentation. So, while the pages look good at GitHub (or with any markdown interpreter), they can show a horrible style within Shorty's help center. Not good.
To get around that, slimdown's limitations have to be obeyed.

Markdown gives us the opportunity to use the same files for the built-in help center as well as for an online documentation (i.e. here at GitHub). But the different interpretations of some syntax elements lead to sometimes very different results. I'm not sure if slimdown is the best choice for this task.

Here are my thoughts after a first test:

• It is slow - Loading pages takes a lot of time. I guess it's because of slimdown's parsing in between.
• The presentation is funny - Chrome and Iceweasel show a very tall card in the middle of the screen
• There is no navigation except for the breadcrumbs on top of the page. That's a bit unconvenient to move between files of the same book/chapter. Especially when there are many of them, which is intended. Jumping through the breadcrumbs means another reload with another slimdown break.
• Some text portions overlap - might be caused by the small width of the box:
• Cross-links between the doc-files don't work, because they reference the full URL, which in turn leads to the start of the help center. (Although I have used relative links, because all the files are in the same location/directory).

I guess that's already enough to work on before we proceed... :smiley:

[arkascha]

This is such great news! It is so much easier to implement and fix issues when you have payload at your hand. I know some SlimDown does have limitations compared to other markdown interpreters. I gave it a try to keep things simple. I agree that the choice of SlimDown has to be questioned. I have no reservations in this. We should also keep in mind that SlimDown can be extended, but as mentioned a few times before I am indeed thinking of using githubs interpreter instead. Not by including it in Shorty, but simply by fetching the rendered results from the online wiki. It has to be answered what happens where there is no access to that online wiki, but that is a secondary question in my eyes. First things first. The advantage of such a strategy are: a single point of truth for editing and rendering the content. A very reliable online help. A convenient embedding into the look and feel of ownCloud. I will give it a try, spike something, let's see. It might mean that the content has to be moved over to the wiki. But as far as I can see that simply means moving the files or at most copy and pasting their content. That should be OK.

About the slim visualization in your Chrome or Iceweasel check: remember that a markdown interpreter only converts the structure from markdown to html. It does not deal with the styling which is the issue you observe here. That is done in separate style sheets I implemented, apparently there are issues in there I have to fix. I am using Chromium myself, not sure currently what the issue here is. Could you provide me with some information about the versions of your browsers and operating system? It might help to track down things...

The "in book navigation" is indeed missing currently. As written before I am working on that. I have not yet pushed anything, since things are not ready. In shorty: the breadcrumbs will get additional embedded dropdown menus preceding the text inside each breadcrumbs, one "hamburger menu" each. Those menus will offer to switch between documents on the same level, be it books, chapters, or whatever.

I did not yet look into cross links. I can well imagine that does not work currently. If switching to embedding the githubs wiki into ownCloud then this i) has to be fixed and ii) will be fixed, since those cross links are normal page request then which have to be handled anyway to fetch the pages in the first place.

I agree with you that it is now my part again to move on with the implementations. You made a terrific job so far. Not talking about the content here, I did not yet take a look. I mention this because of the analytic progress you show: such input is so valuable for me to implement things. Thanks!

[fredl99]

It is so much easier to implement and fix issues when you have payload at your hand.

That's why I pushed it. Although I don't feel happy by exposing unfinished work, we need something to work with.

I agree that the choice of SlimDown has to be questioned.

What about storing the help-files in HTML? They would get bigger, but:

• No need for on-the-fly conversion
• identical look and feel within the App and online.

A webserver is required for OC anyway, so they would be accessible even within an isolated intranet. On- and offline versions of a release are already in sync when they are delivered, because they are in the ./doc/ folder. When a file is parsed a direct link to its online counterpart could be generated for the top or bottom of the page, so that users have quick access to the latest version of the same file between updates. This would also resolve this question even before it appears:

fetching the rendered results from the online wiki. It has to be answered what happens where there is no access to that online wiki

This way the help center would show the docs within OC, and only if the user wants (and is able) to access the latest version, it would open a separate browser window. (Which could as well be a popup-window, in order to preserve the overall look.)

remember that a markdown interpreter only converts the structure from markdown to html. It does not deal with the styling

I know the reason must be somewhere in the sytle-sheets, but couldn't find it.

I am using Chromium myself

And does it look better than what I posted? I tried Chrome Version 40.0.2214.115, Iceweasel 36.0.1 and the Gnome-Browser 3.4.2 on Debian GNU/Linux 7.8