search

CodeSpaceHQ / MENGEL

A framework that applies machine learning algorithms and automates the process of finding the right algorithm for the job.
6 stars 1 forks source link

Documentation & Organization #81

Closed asclines closed 8 years ago

asclines commented 8 years ago

Documentation

According to Wikipedia there are several types of software documentation, a few of which I have reposted below:

  1. Requirements – Statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what will be or has been implemented.
  2. Architecture/Design – Overview of software. Includes relations to an environment and construction principles to be used in design of software components.
  3. Technical – Documentation of code, algorithms, interfaces, and APIs.
  4. End user – Manuals for the end-user, system administrators and support staff.

I believe that our main README.md takes care of the Requirements documentation and seems to at least start documentation the Architecture/Design documentation, however that needs some work.
It is my suggestion that we have a separate README.md that handles the Architecture/Design of this project. It is also my suggestion that this file be in the /modules/ folder as that is where Architecture/Design is most relevant.
Overall, everyone in this project seems to be doing okay adding Technical documentation in their code. That being said, there seems to be some confusion about Technical vs End user documentation and as such, some End-user documentation has appeared in Technical documentation, but otherwise everything is good. Which brings me to the End-user documentation.

First, I want to remind everyone that there is in fact a end-user and therefore there needs to be End-user documentation. We do a good job documentation the top-layer of this repo, but the /modules/ folder and is sub-directories really need more docs.

Now, it could be argued that we don't need end-user documentation in the /modules/ folder as thats all internal to this project, but that is where I would like to politely disagree with you.

We are each other's end-users and we need to start helping each other out by writing documentation.
This means:

And last but not least, this documentation needs to be prominently displayed upon entering the folder. Not hidden or embedded in source code. Think about what you use libraries, where do you go to learn about the library or API. The source code? Or the README.md?

Organization

First off, why are there 12 branches for a team of 5? Are there any of them that can be closed?

Secondly, what is going on with /modules/toolbox/? This may be just on me cause I've been so stuck in my own corner of this project with MLTA but the /modules/toolbox/ confuses the heck out of me.

  1. Is there a better way to reorganize/restructure this folder? It appears that some files are coupled together and other files are completely unrelated.
    • For example, the splitter. Could it have it's own sub-folder of toolbox?
    • Same with the framework tools and runners?
  2. Also, please be more clear with file names. For example the r in r_merge.R. What does the r mean?
isaac-gs commented 8 years ago

I totally agree and just want to add a thing or two.

I'd like to add to this. I think that part of our documentation for the modules section should include explanation of what each subsystem does and what should go in there. That way adding stuff to the project is more clear.

I just want to add that a lot of this is my fault, not only should I have been more careful in designing what goes into modules, but broken windows accumulate (I should have dealt with this sooner in code reviews). So yeah, this is a top priority early this next sprint.

ghost commented 8 years ago

Thank you for this! This is what ive needed I believe. It's been a frustrating few days.

ghost commented 8 years ago

@asclines First off, why are there 12 branches for a team of 5? Are there any of them that can be closed?

In regards to this, I have set up a few branches which are just serving as my templates for the next iteration. Once the other ones have been merged (*crosses fingers it will be soon) my branches can be removed.

isaac-gs commented 8 years ago

@asclines @RyanMcBerg @telelu03 @ZakeryFyke Are there more action items we need to cover for this?

The ones I can think of,

I just want us to keep working on this.

asclines commented 8 years ago

I am closing this issue for two reasons:

  1. The Documentation section of this issue has been migrated to this wiki page
  2. The Organization section of this issue is now being covered in issues #98, #88 directly and in other issues indirectly.