Readme is getting longer and longer

[tomkowz]

Hi,

At first I want to thanks for this repo, it's great for people who want to read about design patterns in swift and it is good for me, for learning others by contributing and sharing our knowledge and for learning myself when I'm wiring examples of some patterns :)

What this issue is about is maintenance Readme.markdown file. I was thinking a little bit and I'm afraid this file is bulky, hard to browse and maintenance. Wouldn't it be better to move all the patterns implementations to separated .swift files and create links in description to these files (with some description optionally)?

The file could looks like this:

/// Pattern name
/// Xcode version

/** Short description
description here
*/

/// Implementation
implementation here

/// Usage
One or more use cases

What do you think about the idea?

[ochococo]

I agree... I like the idea... But the core of this whole repo is the .playground package.

We could split the file, sure... I'll think about it some more and we'll make some move very soon.

[ochococo]

Any ideas how to connect your idea (swift files) with .playground packages?

Mine is:

Separate .markdown, .swift and .playground for every DesignPattern (all autogenerated from .swift file with some ruby script)?

Huh?

[tomkowz]

Sounds good. My idea was to keep each pattern in separated .swift file, and use some script to merge all files together with some description from markdown - so similar to what you're taking about :) But I don't know Ruby :)

[jpotts18]

What about using Github Wiki for documentation and multiple playground files?

[ochococo]

This solution is less portable. Plus - we need some documentation for every pattern. A lot of work.

[jpotts18]

A Github wiki is just a git repository with Markdown files and assets. That seems portable.

On a different note, it seems like the repo could use some renaming and organization.

.
├── docs
│   ├── behavioral.md
│   ├── creational.md
│   └── structural.md
└── patterns (or src)
    ├── behavioral
    │   ├── command.swift
    │   └── iterator.swift
    ├── creational
    │   ├── abstractfactory.swift
    │   ├── builder.swift
    │   ├── factorymethod.swift
    │   ├── prototype.swift
    │   └── singleton.swift
    └── structural
        ├── composite.swift
        └── facade.swift

[jpotts18]

You could also just use another source for your readme.

http://www.blackwasp.co.uk/GangOfFour.aspx

[ochococo]

A Github wiki is just a git repository with Markdown files and assets. That seems portable.

Not so much but something has to be done. I agree.

On a different note, it seems like the repo could use some renaming and organization.

I like the idea, but abstractFactory.swift or abstract_factory.swift is better I think.

You could also just use another source for your readme.

Well I could. We could. Care to help with that?

[jpotts18]

After investigating the current repo structure I understand your problem better. I think this could be a good solution. It isn't rocket science but that is probably means it is the right answer.

Step One - Rename the files

# new proposed documentation section
├── creational
│   ├── 1-title.md
│   ├── 2-singleton.md
│   ├── 3-builder.md
│   └── 4-abstract-factory.md
└── structural
    ├── 1-title.md
    ├── 2-composite.md
    ├── 3-facade.md
    └── 4-adapter.md

Step Two - Combine all of the files into README.md
Generate our Readme file using cat */* > README.md. This will go recursively through the folders and concatenate all of the markdown files together in order of traversal that is why I had to prepend some numbers to files. Because this is a purely text based approach we could also add swift files and have those concatenated into the README.

# Creational
## Singleton
## Builder
## Abstract Factory
# Structural
## Composite
## Facade
## Adapter

Step Three - Add logic to Generate-playground.sh

Disadvantage:

• Prepending numbers and other ordering problems.

Advantages:

• Simple solution
• Text-based approach offers flexibility
• File names are more descriptive
• Generate markdown (or html) for specific sections (i.e. cat creational/* > creational.md | markdown-converter > creational.html

Let me know your thoughts about this approach and I'll gladly contribute it.

[ochococo]

I like this approach, feel free to make that happen.
Not sure we need those prepending numbers. I'd just sort them by name. Prepend title.md with exclamation sign !.

[ochococo]

Oh... Please hurry...
On monday I'll do that myself. 😋

[jpotts18]

Working on it right now

[jpotts18]

#22

[ochococo]

Closing.