Tooling: How Easy, How Deep?

[orcmid]

Come-Uppance

When I realized that Visual Studio Code was flagging my use of HTML in Markdown, I realized it was because I was using a plug-in that flagged such usage by default. In the docdocEng project, it is HTML that will be produced with automatic publication of the docs/ folder.

I can figure out how to selectively remove that warning and/or I could see how the pandoc Markdown extensions help with this in places where publication of HTML is not the (exclusive) objective.

Otherwise, I am in the awkward position of having warnings that I ignore and how that potentially masks warnings that should not be ignored.

About Tooling

There are three tooling cases that need to be addressed somewhere. Pointing and examples may be enough, but sometimes a detailed HowTo may be appropriate. These are not specific to docEng, so there needs to be a better place. nfoTools comes to mind.

1. There is information needed about prerequisite and getting-started use on GitHub. Forking and Cloning needs to be addressed.
2. There is information needed about the GitHub client for Windows and also command-line git usage for organization of clones and coordination with their GitHub-situated originals.
3. There is information about text editing and integration of that with (2). For this, cross-platform use of Visual Studio Code is ideal.
4. Platform variations do need to be dealt with, especially for novices. I can only address how the moving parts can be orchestrated on Windows. Others might contribure equivalents for other user platforms.

Is This Trip Necessary?

It seems that there is a need to simplify this for casual users and writers that do not want to have to deal with the geekiness of a tool chain founded on GitHub as the platform.

To me, that means there need to be savvy editors, but we remove friction from casual contributors. The workflow needs to be understood. We may need some other way to submit and return materials in those cases. This needs to work for someone who is willing to author in Markdown and also someone who prefers to use a customary editable binary format such as .docx or .odt

Will Patterns Help?

This has me trhink that something akin to pattern language without the technicalities may be needed. Pattern language with the technicalities as well for experts, but not required for observers.

There is help-wanted here, for certain..