Changes in Documentation Structure

[David-Lazaro-Fernandez]

Is your feature request related to a problem? Please describe. Currently, when I want to read the content of the documentation I get distracted by all the things I'm looking at in the center of the Screen, I feel there is a lot going on in a small space.

Just on the main page of https://docs.figmagic.com/ there are:

1. Badges
2. Concept Art and Images
3. Heavy White Line Separators
4. Emojis
5. Hard to contrast code lines like the ones in the version indicators
6. Code Blocks
7. Etc

The problem gets bigger when you add the lack of spacing between the sections of the documentation and the sections on this page. If the content itself has a lot of things that distract the user from getting the important content that they want to read or new users who are learning how to use Figmagic, adding these other distractors makes the experience less comfortable for them.

Describe the solution you'd like A clear and concise description of what you want to happen.

I'd love it if we could just restructure the content of the documentation of the page so we can make it cleaner, more readable, and easy to navigate for the users. By adding:

1. More spacing between the "Documentation sections" and the "On this page" section
2. Left align the"On this page" section
3. Have more clear sections to navigate instead of the full route.
4. Use more distinguishable contrast colors for the code lines that currently are on the documentation
5. Use emojis but do not let this distract the user or instead of emojis use white icons that describe the section or subsection

I made a quick mockup for showing what I feel would look awesome :D

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

• Just adding more space between the left - center - and right sections

Additional context

I also added some Feedback and Learn buttons in the mockup so when someone wants to add some feedback it gets redirected to the GitHub Issues and when someone wants to learn about Figmagic they can be redirected to the Figmagic example repo that you have.

Thanks!

[mikaelvesavuori]

Hey @David-Lazaro-Fernandez!

Some really good ideas here.

First and foremost, all the docs are generated with TypeDoc. This limits some creative possibilities, but it seems theming is possible. For example, the left side bar wouldn't be possible, as far as I know.

For structural changes, it's absolutely possible to both move sections around in the Markdown file(s) and also create dedicated sub-pages. See for example the Vision page linked via the main documentation page (README). Note that any of those "sub-pages" won't render at all in the generated site. It's not immediately clear to me how to fix it, but I suppose it should be possible. Maybe this would help?

I'd be happy to make a review of some theme modifications in line with what you are showing. Doing this would only necessitate making changes as per their docs, run npm run docs in the repo, and then check the typedoc-docs folder for the output. Given it's just HTML etc. you can easily run the index.html file locally.

Would I consider changing from Typedoc to something else? Maybe, if we can find a fully covered automated option, of which I don't know many good options today.

Let me know your thoughts.

[mikaelvesavuori]

Hi again @David-Lazaro-Fernandez,

I've done a first stab at addressing some of what you've put on the table. You can check the current state on docs.figmagic.com as always.

Since TypeDoc can take in custom CSS, we can "post-fix" some of what it generates. Making changes is now as simple as updating typedoc.theme.css and re-generating the site.

Regarding the structural changes, I've moved announcements into its own document, and shuffled the content in the main README to separate "designer" from "developer" content a bit.

For all changes, see https://github.com/mikaelvesavuori/figmagic/commit/67ad14a1e0dd17bc3f4de860e25f8f90be49355f

Again, I don't think it's completely possible to do all the changes you'd want to see unless we change the tool.