Discuss: Maintainability of mansion

[dennislwm]

Problem: As more links are added to this repo, the README.md file will be longer.

Solution: Follow the structure of Stack on a budget

README.md is basically a TOC (Table of Contents) and each category has a Markdown file under pages folder.

There will also be fewer merge conflicts if more people contribute to different categories.

[huskypower]

@ytbryan @hadibolehjadi @ylcheryl @shankjs @ReubenChan @dennislwm Hi Lady and Gentlemen, we have an issue here, may we have your thoughts and directions?

[hadibolehjadi]

I agree with Dennis, it will definitely allow the front page of mansion to be cleaner. So it'll mean that each section has its own md. We do need to discuss how we want the structure of the repo to evolve from here, like do we want python.md to be under the python folder? Or under a directory known as pages?

What do you guys think?

[huskypower]

tiddy thing up is the future, moving forward the Readme get longer and losses its appeal and purpose, I had a look at Stack on a budget, and the ideas of documenting is simple and sweet , like hadi mentioned we need to work on the structure .

[shankjs]

Thanks Dennis, Stack on a budget has a nice streamline repo. They have a nice contributing.md that encourages contribution and how to go about it for quicker reviews and merging.. I agree that we can apply it to the mansion. We can have a think on how the structure can be

[huskypower]

Calling @ReubenChan and our lady @ylcheryl your thoughts please for us to move on as we are mentioned to proceed with #42 first

[ReubenChan]

Hi Team,
Sorry for the delay.. agreed on the proper structure of our repo. I have seen the stack on a budget. We should emulate the clean structure and beautify our own ideas ... I believe Cheryl will agree as well... Let's move on

[ylcheryl]

Hi all, Wow! Yes agree totally. Regards,Cheryl On Wednesday, May 5, 2021, 08:54:11 AM GMT+8, reubenchan ***@***.***> wrote: Hi Team, Sorry for the delay.. agreed on the proper structure of our repo. I have seen the stack on a budget. We should emulate the clean structure and beautify our own ideas ... I believe Cheryl will agree as well... Let's move on — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[ytbryan]

Let's do this structure! Stack on a budget has a neat structure for its markdown too. The contributors only need to submit a link, pro, cons. Check out their markdown.

Everyone needs to learn how to merge conflict.

Thanks for bringing this up @dennislwm

[dennislwm]

Hi @shankjs @huskypower @hadibolehjadi @ylcheryl @ReubenChan

Followup on @ytbryan suggestion for a value proposition.

For each resource, I think it should have the following:

Resource Title

• Content type: [video, blog, podcast, git repo etc]
• Short description: [short description]
• Pricing: [free, paid tiers]
• Limitations: [limitations of free]

This is just a quick start, any comments are welcomed.

[ytbryan]

Wow. thanks for this direction @dennislwm brilliant!

Suggestion! We should add some constraint to this to make it succeed faster. For now, we should remove short description. It can come in later (beyond batch 1). Stack on a budget also does not have description.

Welcome the content type field.

Other consideration, will we need more directories instead of one page directory? Or it can come in later?

[shankjs]

Thanks @dennislwm! The structure of content type is definitely a good move forward. There definitely are various forms of contribution. Helps with the classification of content.

Here's a visual representation of the structure. Feel free to use this to tinker on the structure all.

pages.md
|---- azure.md
|---- devops.md
|---- linux.md
|---- python.md
|---- docker.md
|---- github.md

Table of Contents

• Azure
  • Documentation
  • Exam Skill Measurement
  • CLI Installation
• DevOps
  • DevOpsGroup

azure.md

Azure

• Documentation
• Exam Skills Measurement
• CLI Installation

Documentation

Content: Documentation | Ref: Microsoft

Exam Skills Measurement

Content: Website | Ref: Microsoft

Command-Line Installation

Content: Website | Ref: Microsoft

devops.md

DevOps

• DevOpsGroup

DevOpsGroup

Content: Blog

[ytbryan]

I think we should retain our current directory. Note: something & something_else are just names. You decide.

azure/
|------ something.md
|------ something-else.md
devops/
|------ something.md
|------ something-else.md
python/
|------ something.md

instead of

pages/
|---- azure.md
|---- devops.md
|---- linux.md
|---- python.md
|---- docker.md
|---- github.md

directory name should be lower case. markdown name should be lowercase and separated with hyphen. Names must be meaningful and accurate.

[huskypower]

@ytbryan you mean the Folder structure as pre below?

azure/
|------ something.md
|------ something-else.md
devops/
|------ something.md
|------ something-else.md
python/
|------ something.md

the there will be one, two or more .md files? and theses .md files are links to the topics? or are we able to submit files actual files in the folders sure as azure/devops/etc.

[huskypower]

@ytbryan what I meant was

for the folder structure above you mentioned

example:

python/
|------something.md
|------somethinelse.md

that something.md aand somethingelse.md must it be markdown file or can they be actual files such as challenges script and others video?

[ytbryan]

Oh! I think it should be only markdown files.

[huskypower]

@ytbryan we are working on the readme.md file using this structure below?

azure/
|------ something.md
|------ something-else.md
devops/
|------ something.md
|------ something-else.md
python/
|------ something.md

[ytbryan]

azure/
|------ something.md
|------ something-else.md
devops/
|------ something.md
|------ something-else.md
python/
|------ something.md
readme.md

There should be a readme.md file at the highest level. My point is that we already have such directory structure.

[huskypower]

@ytbryan Agree the readme.md is the TOC (table of content) which looks slick and neat at the first page and we have the content , links in the folders as per the TOC.
Content type: [video, blog, podcast, git repo etc]
In the folders eg,

azure/
|-----content type (video)
|-----content type (blog)
|-----content type(git repo)
|-----content type(others to be addedin)

We can either prelist the popular content type in the folder, ready for contributors to add in and or when contributor have a new contact type not in the folder to send a issue request for collaborators to add in and review.

[ReubenChan]

I'm onboard with the new table of content(TOC). It's like our signature design for better visuals.

Or would you like to add a collapsible header for the title for example:

Azure

[ytbryan]

any example repo with the usage? @ReubenChan

[ReubenChan]

I think better not to apply the collapsible title header because of more technical complication when appending with sub titles. @huskypower, @shankjs, and @ytbryan the TOC example looks more structured, neat & tidy

[shankjs]

The TOC is based on a different structure than we currently have. The example was to see how different it would be from our current structure. I have to agree it looks more structured but that would mean changing the current structure. Adding markdowns to the current structure would be easier for all.

azure/
|------ something.md
|------ something-else.md
devops/
|------ something.md
|------ something-else.md
python/
|------ something.md
readme.md

suggestion for various content type(s), they can be linked within the markdown
i.e.
-[Youtube - Installing ubuntu 18.04 on virtual box ](URL)