Message from the devs: Is there more documentation needed?

Hello to everyone here listening to this category!

TL;DR

We would like anyone interested in the app to take part in a very short survey (<=5min) about the documentation of the app. It is due on August 31st 2021.

The longer version

I am one of the devs of the cookbook app. I am a bit concerned that the documentation of the whole project is not sufficient. This can both affect new users wanting to use the app as well as developers that want to contribute to the code in any way. Documentation is sort of a key in communication.

Creating documentation, tips&tricks, and the like requires some time and is maybe even better written by someone who is using the app mainly. We devs have sort of a different view on the app. So, we would welcome any contribution in this direction. However, there is not happening much in this direction.

Now, we do not know if this is due to the lacking need for documentation (then we will not waste manpower on this of course) or for other reasons. As we want to give the best experience to the users (within our options of course of volunteers), we wanted to ask you about your opinion: Please take part in the survey. It is hosted on my private NC instance to avoid any 3rd party (like google) involved. I will not pass any personal data on.

To have a clear deadline, the survey will close itself on 2021-08-31T21:55:00Z.

If you had any comments/questions, feel free to ask. You can also reach me in room #nextcloud-cookbook:matrix.org of the matrix network or directly there.

Thank you very much!

Done. Not sure how much help I can be, but I’ll give it a go :slight_smile:

1 Like

Hello to everyone involved here in the project. I want to share the result of the survey here (minus the personal data). I will try to interpret this a bit.

However, only 5 people did participate in the survey. So, the results cannot be considered as well-posed statistics but only a very small sample.

Is the documentation page known?

The main intention was if the enhancement of the documentation in the named page does even make sense. If not, more promotion or a better format might be considerable.
Q1 - Did you know the doc page

The interpretation is not very representative as too few people have participated but there is at least a favor for the knowledge of the page. So, I’d say, we can use it as a communication platform of documentation and try to promote further.

Required documentation

The question here is how much documentation to write in general. We do not want to put too much manpower into documentation if it is not read anyways.

First good point is that no participant was lost on the app’s usage and requested more information. This means we did not mess up the UI completely :blush:.
Apart from that, quite some users would have anticipated some beginner’s documentation.

Required topics

In order to write user-centered documentation, one needs to know what topics to enhance. There was a free-form text to state something else.
Q3 - Required documentation

The main request seems to be related to the usage and administration of the app. However, when looking at the individual answers, it seems that there are two groups of users (also comparing/correlating with other answers):

  • The tech-savvy ones that are more into administration and potential participation in the development
  • The normal users of the app that need an introduction to how to use the app.

Help by the community

For the sake of saving manpower on the programming part, the question is if the community is able to participate in the documentation and keeping it up to date. That would allow the documentation to evolve also without binding too many resources.
Q5 - Support documentation

One can see that a majority of users are not able or willing to help. This is not necessarily surprising as the survey was not posed within a group of power users but in a mixed environment.

The other (two) users were willing to help but were not aware of the possibility or the possible topics. I will contact them separately soon. We will see how we can get this running.

Anyways, if you find a topic that needs documentation coverage, please feel free to contact me on GitHub or here. We need mainly a good structure and the requirements for a good documentation. If you contact me here, don’t forger to mention me using @christianlupus.

Misc

The final question was if there was something missing in the survey. I put it here for sake of completeness.

Regarding the sharing of recipes, we are on your war to restructure the source code to allow this. At the moment it is not possible to to missing fine-grained data storage. This is on the agenda as soon as our tests are running and we are sure, we are not breaking the complete system.

We appreciate the thanks for the app very much!

Regarding the exiting documentation and experience writing it, as stated above, I will contact you soon.

Thank you for participating!