Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Complex documentation structure #2891

Open
Chemin1 opened this issue Aug 17, 2019 · 5 comments

Comments

@Chemin1
Copy link
Contributor

commented Aug 17, 2019

In our last offline meeting I expressed my concerns about the structure of our documentation. In my opinion it is not easily comprehensible where I can find what I am looking for.

Two examples from the last 20 minutes:

  1. @markus2330 and I have talked a lot about doc/METADATA.ini. When looking through some folders I suddenly find doc/dev/metadata.md. Even though I knew most of its contents through inspecting the source code during the last weeks, I have never seen this file before. It is not on the website at "Elektra Developers", it is not in one file with METADATA.ini. Of course, I can think of some logic that explains why this file is placed where it is (It's not a tutorial, thus not on the website but also more developer-relevant than METADATA.ini). Nonetheless, I could have used this information for weeks and have not seen it.

  2. I wanted to use docker to run the reformatting-scripts and navigated to libelektra.org as I find it the visually most appealing way to read our documentation. There I found the article "Run Reformatting with Docker". This was OK.

However, I wondered why it suddenly says "libelektra-sid". I built "buildelektra-stretch-full" some days ago. Why is there suddenly sid? Consequently, I looked for the guide that talked about "stretch-full". It took some time until I found it at scripts/docker/README.md. And again, it kind of makes sense to put an accompanying README to the docker scripts. This, however, does not change my confusion. Can I find it (the file I was looking for) on the website, is it in doc, some subdirectory of it or somewhere completely different?

Unfortunately, I do not have a fantastic idea to solve this. However, I'd be really interested in other people's experiences with this! Maybe I'm the only one having those problems, but maybe there is also some pattern of struggles.

@markus2330

This comment has been minimized.

Copy link
Contributor

commented Aug 17, 2019

Thank you for your very helpful input! These two concrete problems should be solvable quite easily.

I think the main challenge is that we generate the website from the in-source docu. Of course this is a good idea from the point of duplication but it also leads to the problems you describe above.

The way forward is what we are already doing since quite some time: we add tutorials that are easy to read and have a linear structure. With tutorials in place, there are usually no more complaints that something cannot be found but only complaints that the tutorials do not work (and for this we also already have a fix: the tutorial wrapper of the shell recorder checks if code in tutorials produce correct output and return values).

Unfortunately, we do not have a tutorial for METADATA.ini yet. It would be great if you can help me writing such a tutorial.

@kodebach

This comment has been minimized.

Copy link
Contributor

commented Aug 19, 2019

However, I wondered why it suddenly says "libelektra-sid" ...

I think we shouldn't recommend the use of the full build server docker image for reformatting. IMO we should provide a minimal image that contains the correct clang-format, cmake-format, prettier and shfmt versions. Building the full docker image can take a very long time.

@markus2330

This comment has been minimized.

Copy link
Contributor

commented Aug 19, 2019

Is reformatting in a Docker container really something a regular developer would do? The idea of that container was only to make it easier for first-time contributors. And the first-time contributor might also want to compile Elektra and run all tests cases and so on (see other tutorial: run_all_tests_with_docker.md ).

IMO we should provide a minimal image [...]

Yes, there are many possible improvements for the Docker images. I am keen of having Docker images with Elektra directly from our build server (pushed to some public registry). Unfortunately, until now nobody had time for this. But someone already showed interest on working on the continuous releases.

Anyway: we see from the discussion: in the moment the tutorials exist, the discussions are about how to improve the tutorials (and not about the troubles not finding something).

@Chemin1

This comment has been minimized.

Copy link
Contributor Author

commented Aug 19, 2019

Is reformatting in a Docker container really something a regular developer would do?

I have already spent some time downloading all the stuff that is necessary to run the different reformat scripts. Until today, it's not working and using the docker container is really convenient for me.

@kodebach

This comment has been minimized.

Copy link
Contributor

commented Aug 19, 2019

The main problem is that clang-format often has breaking changes and not all distros have compatible versions in their repositories. That's why I use a special docker image that only contains the correct clang-format version. I then call that image via a shell script called clang-format-7, so it is also picked up by our reformat scripts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.