Create readme for Project/Database-IO

[aubertc]

The folder https://github.com/popbr/data-integration/tree/main/Project/Database-IO does not contain a README or a manual. Should be documented:

• How to compile,
• How to execute,
• Which parameter(s) can be tweaked (typically, the user / password of the database user),
• How to use the project.

As far as I can tell, the only way to figure all of this is to read the source code, which is not ideal.

[aubertc]

This is what I meant by "document your source code": as of now, there is no "big picture", only small comments letting the programmer knows that this particular statement does that. But somebody simply willing to use the program would be quite helpless.

[MNSleeper]

I added a Readme addressing these points

[aubertc]

Ok, so https://github.com/popbr/data-integration/blob/main/Installation_Test/DataIntegration_ReadMe.md is a good start. A couple of comments:

• It should be a ReadMe.md in the https://github.com/popbr/data-integration/tree/main/Project/Database-IO folder, shouldn't it?
• You can add comments using (cf. https://github.com/popbr/data-integration/commit/91b96029e86de4ce0c345c3f57f43bf4142f5fb9 )
• Your instructions looks too much like a tale. Make lists, go to the point. Cf. https://github.com/statycc/pymwp#running-from-source for instance. Explain how to clone, unzip, navigate to the folder more directly.
• I like the "database scanned" principle, but you should give an example.

That's all for now, but I can either do some of that if you prefer, or think more about it.

[MNSleeper]

It should be in the Database-IO folder, I mistakenly placed it there. I'll fix that. Also, are you suggesting I comment out your guidelines at the top of the document?

[aubertc]

It should be in the Database-IO folder, I mistakenly placed it there. I'll fix that.

Thanks. I don't know if it is good practice to put it directly in the main folder, though. Maven may have other ways of doing with docs.

Also, are you suggesting I comment out your guidelines at the top of the document?

No, I was suggesting to do exactly what I did with https://github.com/popbr/data-integration/commit/91b96029e86de4ce0c345c3f57f43bf4142f5fb9 and informing you of the fact that you could have comments in markdown using <!-- -->.

[MNSleeper]

I have added comments. thank you for the suggestion.

[MNSleeper]

Uploaded a modified Readme.md version 1.2. I do need to ask what commands there are to download SQL and Java environments. If there are none and I'm confusing you, then I'll take it out.

[aubertc]

I have added some small comments in https://github.com/popbr/data-integration/commit/6b0e6638ca9eeab9cc8d8a74e6f167d23b161cbc

[MNSleeper]

I have replaced the readme(s) with one singlur ReadMe that incorporates the suggestions you gave

[aubertc]

You mean DataIntegration_ReadMe.md? The name should just be ReadMe.md.

A few comments:

Run the installation test and see if the same error persists.

Add a link to the installation test.

Note: Is that something that should be suggested? should it be one of our emails instead?

No, opening an issue is the way to go.

git clone https://github.com/popbr/data-integration.git

Use the code environment rather than a quotation for commands.

Finally, please don't hesitate to read other project's readmes to get into the "style". Those are generally short & to the point.

[MNSleeper]

By link to Installation Test, do you mean "https://github.com/popbr/data-integration/Installation_Test.git?

[aubertc]

This link is in error, have you tried it? I meant something like https://github.com/popbr/data-integration/tree/main/Installation_Test Imagine being somebody that never used this tool, you want to give indications as precise as possible, so including a simple link will go a long way.

[MNSleeper]

You're right, I meant that link. I've included it.

[aubertc]

Ok, this file can probably be tweaked and improved, but at least it exists and contains the minimum, so we can close this.