What do you think of this style of documentation?

1

During my work on scss framework http://prettyminimal.com/csstetic/docs/ I have made a test-documentation of simmilar kind, about Meteor features - here: http://www.prettyminimal.com/projects/codesnippets/meteor/v0.1/docs

It has auto-scrolling sidebar, detetcion of visible sections, and few other features, what do you think of this kind of documentation, is it clear and easy to read?

8 Likes
2

Looks very nice. :slight_smile: Good job.

3

Thanks, I appreciate that!

4

I actually opened this site wanting to find something to complain about. So the fact I didn’t find anything has its weight.

5

Hmm, I’m not sure what “has it’s weight” means, but I know there is always a lot to improve, but the right question is - is it worth the time, who will use it, will it be used and so on :wink:

6

If the content is good, I will for sure be recommending it to newbies. They often complain that the materials are either too complex, out of date or unreadable (especially the docs).

Everytime I have to explain people that AccountsClientOrServer doesn’t really exist, something breaks in my heart.[quote=“antraxis, post:5, topic:20699”]
Hmm, I’m not sure what “has its weight” means
[/quote]
Probably untranslatable idiom for “means a lot”.

7

Always looking for ways to improve the meteor docs! Now that we have the guide it should be easier to tear them apart and rebuild something much better. My only concern with most documentation tools I’ve seen is - how do they scale to 200 API functions? Meteor is quite a bit larger in surface area than most other libraries out there.

3 Likes
8

Bit long response…

@sashko the problem for big documentations applies both to content section and sidebar navigation. In my documentations about 30 features is much enough to fill entire height of the screen… I think next thing would be adding tiny search form at the top of navigation sidebar or add infinite nesting on sidebar, just like online shopping websites do (each product is placed under very specific, nested category).

I tried to document all-features on one page, and then split each feature into clickable tabs - even if that made docs about 2-3 times lighter - it’s still heavy after all, so now I would consider presenting features on separate pages (like bootstrap 3/4), or make a script to expand only the sections which are in current category, and fold the others - this would make browser scrollbar not-so scary long.

One more thing - separate from documentation, add a presentation pages, just to show what we are talking about on the demos - for visual perceiving persons, such as i am, and i think many front-end related developers too.

9

Oh, I just went to the site on desktop… when I first visited it was on mobile, and it wasn’t very good at all - couldn’t navigate, etc. Is the site intended to be mobile-friendly?

10

The csstetic is using an updated version of “documentation module” (mobile friendly), and meteor code snippets use the old version (desktop only), it is easy to update it for mobile too, because documentation and documents are separate.

11

Looks great and modern for now. I like the copy buttons.

Is it custom ?

12

Yes, it’s all made from scratch, written in Jade.

code sections look like this:

div
  :code
    <span class="button...">...</span> // this tag will be available to copy

and then code language is detected, highlighted with highlight.js and so on.

13

Looks nice, one bug though if I click on the link on the left the “title” flashes and then disappears on Chrome.

14

@trajano Nice catch, it was intended to disappear since the title of current section is copied to Title bar above it, but in case of that looking like a bug - i removed that in a newer version of documentation (which my csstetic framework is using).