Good Practices when contributing to the documentation

Thanks for the docs section, V! Nice work. Still though… no mention of proof-reading, spell-checking, or English-ish grammar/punctuation. hmm.

Tiz ok… maybe I’m a “lone ranger” on those things, and the How To Contribute to Docs -doc is already large enough to scare-off most potential docs contributors. heh.

For @Deltakosh … I agree with clicks… simply because I am a serious text highlighter/copier, and sometimes mouseovers interfere with that. On a different and highly-pending subject…

… Is there any “hint” about IF/NOT there is enough budget for a full-time mostly-docs-only employee?

This is important to know, for us, here, because… IF a full-time docs employee COULD be hired, then “How to Contribute to Docs” becomes “Send Docs-change proposal to the Docs Dictator username”.

And then our “best practices” area becomes “How to format a docs-change proposal… before submitting it to the Docs Dictator.” :slight_smile:

Budget for such or not, preferences and priorities of others… are definitely involved, here. A docs employee, gently guided by DK and JK and Vinc and self-wisdom and “good docs policies”… completely changes “the ball game”. If it IS “within reach”… then somebody needs to TRY the reach. What the heck. I think it’s a fine idea, but lots of potential obstacles could be in the trail ahead.

BTW, me/we seeking a FT docs-meister… is NOT related-to the great work done by senior docs custodian @JohnK . He has done an exemplary job with docs writing and wrangling, as have many many others. I’m also NOT saying that the BabylonJS docs are weak or insufficient in ANY way. I think they are pretty darned nice, actually.

But the “central point of contributing” and “central point of docs policy-adherence”… really comes into ease and prominence… IF a full-time docs employee (a good one)… is employed/deployed (and somewhat/softly under the watchful JohnK advisory umbrella). Perhaps… this person is hired under the MS offices in England… allowing some face-to-face discussion picnics for/with JohnK.

Hey, nobody does English better than the English. :wink: Thoughts, anyone?

Every moment that this employee isn’t working on day-to-day docs maintenance, they grow the glossary a little bigger. Since they are doing docs builds AND glossary, they (with JohnK) determine when/where to apply glossary terms (within the docs). If they install a term in the glossary, then they also install the hot-links to that term… throughout the docs. They are working both-sides of THAT project… both the building-of the glossary, and the implementation of its added docs power.

All docs contributions… are simply suggestions sent to the DD (docs dictator) (docs director?)… easy “fire and forget” from the users-side. The DD could also have a pinned thread or two… where we all can publicly discuss a docs change/addition proposal. No more needing to learn github… to contribute to docs or repair docs typos/wordings. Easy.

Thinkin’. :slight_smile: Thanks again, Vinc… a fine addition to the contributing doc.

Not at all, I just missed the proposal. As I’m not a native english speaker, your posts can be harsh to read :blush: I add this to my todo list (unless someone wants to make the PR)

1 Like

My posts are harsh to read for ME TOO, and many other native English speakers. :smiley:

Never enough “WebGirLs” in my life. heh. In fact, never ANY. It seems like FOREVER since I’ve had a good onPointerMove observation. :wink:

1 Like

:wink: doc contribue: wingnut suggestions by Vinc3r · Pull Request #1822 · BabylonJS/Documentation · GitHub

1 Like

The flash cards are a good idea. For all API link travellers here I would suggest to include a hint into the guide to link all class or method mentions to their corresponding API documentation.

Together with the flash card you could get a feeling like in an IDE where you hover over a function name in your code and get a short description of it including parameters and so in a tooltip!

1 Like