Technical documentation page all vanilla

Code Feedback
1

Hello good people

Please have a look at my technical documentation page and give me any feedback/suggestions you like.

I’ve commented out the testing script for the moment as it was behaving strangely (appearing translucent and unusable).

Code is here: https://github.com/ozmos/technical-documentation-page

2

Looks cool, but it has some small issues about layouting, and I would give some suggestions.

First Why the panel at the left is not fixed?! When user scroll the content panel/page the navigation panel also scrolls. I think it should be supposed fixed.

But for mobile, it’s really great. I see it goes at the top, and it’s togglable, very good.
For mobile you may either set the top navigation fixed, or have a quick button at the bottom of page for instance to jump to top.

In any way, user should access the navigation panel very easy without scrolling too much.

I see you apply some background colour for code snippet sections, very good. Bu I don’t know why did you not let them display as a block?! let them fit the parent bound. (remove theat width:50% from .code-section rule)

For mobile a little more line-height could be great. Also add a little more space between each paragraph.
I see you place <br/> tag inside <p> paragraph tags. I suggest instead of adding <br/> you close the paragraph, and start another one. Except when two sentence are really related to each other.

If you could caption each code section and images could be awesome.

Adding a horizontal line <hr/> after each title in reading panel could be great.

I think if you could center images could be better.

Also use inline-code too. In your description, whenever it’s about keywords or any inline code, make it as inline code too. for example considering following paragraph

Typically if we had all of our items set to flex: 1 1 200px and then wanted one item to grow at twice the rate, we would set that item to flex: 2 1 200px. However you could use flex: 10 1 200px and flex: 20 1 200px if you wanted.

Note the inlined section. also let inlined codes come with a background colour just like you did for block codes.

Very good overall, like to see some progress and update about the fixed navigation soon.

Keep goin on great work, happy programming.

3

Nice design, it looks really professional and I like the color scheme. Also good job on the responsiveness.

If I may give a suggestion as also @NULL_dev mentioned I would make the menu fixed so it easier for users to navigate the page.

4

Thanks for feedback and suggestions. They are all on the to do list.

@NULL_dev While you were looking at the code, did you happen to notice anything about it that might be causing the fcc testing facility to be acting wonky? The other scripts work fine but that one is acting up for some reason.

5

All changes now live. Thanks for the feedback and suggestions. Looks and functions better now.

6

Update looks very good now, good progress.

the very tiny issue is when you click on any subject at the navigation panel, it scrolls a little more, and stops just after the title. This is I think the default behavior, but you may place the inline anchor above the title, and make it hidden. this will fix it I think.

Another suggestion, have a small script, to find all images and code snippets on your page when page is loaded and cption them as figure 0, figure 1, … code snippet 0, code snippet 1, … If you could add one caption(deccription) to each code snippet and figure could be awesome then. but try to number than using some script.

Keep goin on great work, happy programming.

7

hello again @ozmos look’s cool good

8

My 2 cents. Code snippets’ area looks better when it’s as wide as text, or at least all the same width.
P.S. the page looks great.

9

Thanks. You mean the code block would look better if the grey background spanned the whole width of the page?

10

Yes. Look at fcc forum code snippets or stack overflow

Like this :-)
11

Cool. Thanks, I’ll change it later

12

Thanks, on the to do list. When you suggest to caption each IMG and snippet as figure 1 figure 2 etc, is this because it’s considered best practice for technical documents?

13

Yes could be.

Having caption for code snippets, figures and objects could help you to refer them very easy in your article. For example you are talking about CSS grid in 5th page, and would like to inform user to back in page 2, and ask user to have a review of grid code snippet. So simple you may ask the user check code snippet x.
Even better, as you placed inline anchor for title parts, you may do the same thing for code snippets too, so when user click on snippet code x it jumps to the related cod snippet.

Also note, even if you not pointing to any internal code snippet, having caption still make sense for users like to share your page with someone else and like to address a particular code snippet, so caption could help here too.

This also may be funny, but some users(usually ones prefer tl;dr version of text stuffs) check elements of a page first, so if a code snippet come with a caption like “code snippet 2: using grid for layouting sample” this help the user not read the related text and description to understand subject of the code part, so she/he is happy!

I would say not everyone do caption stuffs, but I believe it’s a good thing to label and caption elements.

Keep goin on great work, happy programming.

14

Thanks for the detailed and patient explanation.