A section for guides about docs

[Qard]

Sounds less "best practices" and more "here be dragons", but I agree that it'd be good to document some of the weird and unexpected things users might need to be aware of.

[jorangreef]

Thanks @silverwind .

Just to urge that the docs should not make it out to be a thorny issue. It's actually very simple and straightforward to work with when one takes a few minutes to understand it. It's filesystems 101 essentially. When people don't understand how Unicode normalization works they tend to panic and reach for the normalize-everything footgun. That's the real danger.

Perhaps it would be good to start with a section on non-case preserving filesystems to make people aware of that and then frame the Unicode normalization in the same light (it is exactly the same concept). And also to emphasize that normalization should only ever be used to compare data, never to change it when storing or passing on. A few links to some of Linus' rants might also help.

[jorangreef]

I can help with writing out a draft for this if needed.

[Qard]

I didn't refer to it as "here be dragons" due to difficulty, it was because it's a thing that can easily be an invisible footgun, so awareness is important. I generally read "best practices" as, "these are some good ways to do a thing" and not "absolutely do this, or you will suffer".

Also, I'm not sure linking to Linus' rants is quite the tone we'd want to set.

[silverwind]

I don't particulary like 'here be dragons', as I hear a certain tone of 'unfinished content', or as Wikipedia puts it:

"Here be dragons" means dangerous or unexplored territories, in imitation of a supposed medieval practice of putting dragons, sea serpents and other mythological creatures in uncharted areas of maps.

'Best practice' implies to me that there is a bad practice that will bite you in edge cases, but I'm open to more suggestions of course. Naming things is hard.

@jorangreef you are very knowledgeable on this subject, and I'd love if you could write something up once we've decided on a name. I think it'd best handled in a PR to the website repo then.

[jorangreef]

@silverwind I have a draft "Best practices when working with filesystems" which is up at: https://www.dropbox.com/s/7b1swypm08v76wo/Best%20practices%20when%20working%20with%20filesystems.html?dl=0

It focuses on case, Unicode form and timestamp resolution differences between filesystems. These are similar concepts and once understood they can be applied to other aspects of filesystem differences such as inodes, permissions etc. I picked these three since they are similar and help to reinforce the idea that code needs to take filesystem behavior into account and preserve user data as much as possible, without resorting to a lowest common denominator approach. Please let me know what you think and what can be improved.

Should this be linked to under "File System" in the API docs? Perhaps with a short 1 paragraph summary? Should I submit the pull request to nodejs/node?

[silverwind]

I'll read up on that on the weekend, thanks.

I think it would fit nicely in a separate section at https://nodejs.org/en/docs/, which is likely managed on the website repo. Of course we should like to it eventually from fs and the relevant process methods.

[silverwind]

Some more title suggestions:

• Working with Node.js
• Gotchas (Strikes me a bit as a slang)
• Common Pitfalls (might be too negative)

[silverwind]

@jorangreef wow, you went into great detail there, great writeup indeed!

I'd say as a first step, you create a PR on the website repo to add it in markdown form, just like this one here: nodejs/nodejs.org#218.

I think at this kind of detail, this would qualify and warrant a 'guides' section.

[jorangreef]

Thanks @silverwind I have created the pull request at nodejs/nodejs.org#249

At the moment it is not linked to from the docs anywhere. Will someone else create the guides section?

[silverwind]

Oh by the way, this is fixed: https://nodejs.org/en/docs/guides/