selfdefined
[Project] Rewrite Self-Defined docs
Challenge
I think Self-Defined's docs would benefit from both a content and structure overall. We have an opportunity to make navigating them more intuitive, and to use them to cover a broader base of knowledge. With these changes, we could make Self-Defined more beginner-inclusive and perhaps even teach them a few programming skills.
Goals
I'd love feedback on the matter of what, exactly, is in scope for this project. Some ideas:
- Write a page dedicated to helping the reader set up their local dev environment (Install each of: a text editor, Node, NPM, Git/Gitbash)
- Explain the technologies and languages used to write Self-Defined
- What is Eleventy? How do I use Nunjucks? Explain a bit about each, and/or link to helpful reading
- What is Sass and how do I use it to write CSS? Write or link to explanations
- Write a page or pages to walk through important parts of the code base
- Explain our templates, layouts, shortcodes, and Eleventy config
- Explain our Sass structure
- Make our definition examples more robust
I am happy to take on this project, and equally to share it with anyone who would like to help!
I absolutely LOVE that this is ticket number 100. So many parts of me are happy right now.
Oh! @dengeist I'm a jerk and never responded here! I feel like I dreamed that I did and considered it done (ok don't judge me for dreaming about this)
OK! So, a few broad things:
- I think that a lot of the content I'm in the midst of writing about for my own blog could be reused or linked to from here for Eleventy core structure, setting up dev environment, etc.
- I think organisationally, it could be helpful to break down contribution by type:
Visual: Explain here Sass, how CSS is organised, etc Infrastructural: How definitions are generated, flagged, interlinked Writing: Submitting words as suggestions, submitting definitions (break down parts of a definition, key common sections [e.g., issues, impact, further reading])
The rest of your outline seems like a great starting point. I think it would be lovely if we could start by assigning an outline, where we can define the broad spectrum dev landing page and its subpages, then create a to do list in this issue's description to track.
Does that make sense to you? Open to doing it another way if you have ideas!
