Improve getting started

[zak39]

Hi @juliushaertl and @julien-nc :)

I propose an improvement on the documentation :)

But, this PR is not yet complete. Indeed, I need to get feedbacks from Nextcloud developers and a community of developers (No Nextcloud developers or employees).

When these checkboxes are checked, I consider this PR completed, and I will remove the draft label*.

• [ ] Get at least 5 feedbacks from a community of developers
• [ ] Get at least 5 feedbacks from Nextcloud developers or employees

Please, if you have the time, could you ask your coworkers what they think of this "new" documentation ? :pray:

You can look at the result here :point_right: https://github.com/arawa/nextcloud-docker-dev/tree/doc/improve-getting-started

[zak39]

Very nice, thanks a lot already for all the work. I left a few comments inline.

You're welcome ! :wink:

But, I don't know how to use all containers (Blackfire, Collabora, Saml, Imaginary and so on.).

So, you should consider my PR as a basic structure and not as a final documentation :)

I have designed this structure as a module. If, one day, we have a developer a new feature / component for this project. She/He will add this new feature / component in the features list, in the "Different feature you can use" section.

Do you see the idea ? :)

[zak39]

Hi @juliushaertl :wave:

I updated the documentation to run another version of Nextcloud : https://github.com/juliushaertl/nextcloud-docker-dev/pull/87/commits/9fe9983a456d76a3fac456d6eeaa03ecd5f29e6b

Indeed, I had the same problem that @Apfelwurm (issue : https://github.com/juliushaertl/nextcloud-docker-dev/issues/85 ) and I ran these commands to fix my problems :

git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

Can you tell me if it's okay for you ?

[juliusknorr]

@zak39 While i think this is a great idea to improve the documentation and its structure i feel we should rather approach this in smaller steps. Would you be fine to open smaller pull requests to rather change just individual sections or move individual sections out to separate files instead of the large one? That might be a faster way forward and also avoids that we by accident leave out some newly added details in the docs.

[zak39]

@zak39 While i think this is a great idea to improve the documentation and its structure i feel we should rather approach this in smaller steps. Would you be fine to open smaller pull requests to rather change just individual sections or move individual sections out to separate files instead of the large one? That might be a faster way forward and also avoids that we by accident leave out some newly added details in the docs.

@juliushaertl I agree. Yes I can open smaller Pull-Requests and do this step by step. But, in my idea it's to split the technical stacks with links to pages in specefic folders. This is the case in this PR.

But, I think it's a good idea to ask internal and community developers for their opinions on the subject. Otherwise, we will have something that is clean for us, but not necessarily for others.

When I will start the first Pull-Request, I will create a subject in the Nextcloud's Discource (help.nextcloud) for the community. But, I don't know how to communicate on this subject with the Nextcloud's internal developers :confused:

I am not a Docker expert. But after the documentation part, I think it's very interesting to improve performance of the docker-compose : faster to execute containers, maybe simplify docker-compose, and so on ?

I have heard that it's possible to run containers in parallel. Maybe it's very interesting to do this ? I don't know ^^'

[juliusknorr]

But, I think it's a good idea to ask internal and community developers for their opinions on the subject. Otherwise, we will have something that is clean for us, but not necessarily for others.

Agreed, but i feel like getting feedback is hard for large changesets. I think that the Readme was improved quite a bit with small feedback cycles from contributions.

When I will start the first Pull-Request, I will create a subject in the Nextcloud's Discource (help.nextcloud) for the community. But, I don't know how to communicate on this subject with the Nextcloud's internal developers 😕

I wouldn't make a difference there. The forum is a good place for both parties to discuss.

I am not a Docker expert. But after the documentation part, I think it's very interesting to improve performance of the docker-compose : faster to execute containers, maybe simplify docker-compose, and so on ? I have heard that it's possible to run containers in parallel. Maybe it's very interesting to do this ? I don't know ^^'

Sounds like something to discuss in a separate issue in this repo. I'd be especially interested which parts you consider slow. Containers generally run in parallel, so I'm not sure I see what this would solve in terms of performance. A general note, the development setup is likely not as performant as a productive setup if xdebug, debug mode and other additional tools are enabled, but if there is something we can improve I'm of course very open to discuss :)

[juliusknorr]

@zak39 Thanks for your effort on this so far. I started creating a separate docs folder that uses mkdocs to build them at https://juliushaertl.github.io/nextcloud-docker-dev/ I'll start moving over the readme parts to that and probably improve those also during the migration.

I'd say we continue with that and improve the parts iteratively. Pull requests for that in small chunks would of course be very welcome.

[zak39]

Hi @juliushaertl :wave:

Thanks for your compliments :slightly_smiling_face: It's really cool your documentation :+1:

I will base on your documentation and if I need to add sections and more, I will contribute your documentation :wink: Iteratively, of course :+1:

Is mkdocs based on Sphynx?

[juliusknorr]

No mkdocs is different tooling then sphinx, a bit simpler and only supporting markdown (no rst), I don't have strong oppinions on the tooling (except on using markdown), but it was the quickest to get started with.

[zak39]

Yes, of course!

The UI reminds me of Sphynx and I was surprised ^^

Cool if it's very simpler than Sphynx! I love MarkDown :heart:

[juliusknorr]

Yeah it is the readthedocs theme which is available for both :)